Refactor FE API v2 interface + current visitors bugfix (#6351)

* more specific type to event:props:* dimension

* rename use-order-by.ts -> use-metric-order-by.ts

* SortDirection: use string union type from query-api-schema instead of enum

* use query-api-schema pagination type too

* add proper OrderBy type (with dimensions) and separate MetricOrderBy

* use NonTimeDimension type in v2 breakdown components

* also create a Dimension type (incl time dims)

* create use-query-api.ts

- usePaginatedQueryApi -> useSearchAndPaginateQueryApi (include addSearchFilter logic in the hook)
- enforce dimensions on ReportParams type and make it a part of queryKey
- define explicit StatsReportQueryKey type

* add a useQueryApi hook and use it in IndexBreakdown

The new hook also includes automatic realtime re-fetch logic.

* Add CurrentVisitorsContext

- fixes a bug: current visitors in realtime top stats, in shared links limited to segment, are fetched from /query api which enforces segment filter -> 400 Bad Request
- uses Tanstack useQuery against the old GET endpoint
- The value is now also cached for 30s (CACHE_TTL_REALTIME)
- Do not fetch current visitors at all when not needed (i.e. not realtime and dashboard has filters applied).
- The same context value is now used by both top-stats.js and current-visitors.js

* top stats and main graph to useQueryApi

* DetailsBreakdown: addSearchFilter -> searchEnabled

* extractIntervalFromDimensions utility

* create new statsQuery with spread

* remove redundant useMemo

* remove redundant as type casts

* move and improve comment

Author: RobertJoonas

assets/js/dashboard/api.ts

@@ -5,6 +5,7 @@ import { StatsQuery } from './stats-query'
 import { formatISO } from './util/date'
 import { serializeApiFilters } from './util/filters'
 import * as url from './util/url'
+import { MainGraphResponse } from './stats/graph/fetch-main-graph'
 
 let abortController = new AbortController()
 let SHARED_LINK_AUTH: null | string = null
@@ -37,10 +38,21 @@ export type QueryResultRow = {
   comparison?: { metrics: Array<number>; change: Array<number> }
 }
 
+// Added client-side in the queryFn before storing to TanStack cache.
+// Needed to make sure that the time/metric labels we're constructing
+// in stats reports are in sync with the dashboardState that was used
+// to make that query. Otherwise, relying on current dashboardState
+// while rendering previous (placeholder) data, it'd be out of sync.
+export type ExtraContext = {
+  isRealtime: boolean
+  hasConversionGoalFilter: boolean
+}
+
 export type QueryApiResponse = {
   query: QueryResultQuery
   meta: QueryResultMeta
   results: QueryResultRow[]
+  extraContext: ExtraContext
 }
 
 export class ApiError extends Error {
@@ -141,7 +153,9 @@ function getSharedLinkSearchParams(): Record<string, string> {
   return SHARED_LINK_AUTH ? { auth: SHARED_LINK_AUTH } : {}
 }
 
-export async function stats(site: PlausibleSite, statsQuery: StatsQuery) {
+export async function stats<
+  TResponse extends QueryApiResponse | MainGraphResponse
+>(site: PlausibleSite, statsQuery: StatsQuery) {
   const sharedLinkParams = getSharedLinkSearchParams()
   const queryString = sharedLinkParams.auth
     ? new URLSearchParams(sharedLinkParams).toString()
@@ -158,7 +172,7 @@ export async function stats(site: PlausibleSite, statsQuery: StatsQuery) {
     body: JSON.stringify(statsQuery)
   })
 
-  return handleApiResponse(response)
+  return (await handleApiResponse(response)) as TResponse
 }
 
 export async function get(

assets/js/dashboard/components/sort-button.tsx

@@ -1,5 +1,6 @@
 import React, { ReactNode } from 'react'
-import { cycleSortDirection, SortDirection } from '../hooks/use-order-by-legacy'
+import { cycleSortDirection } from '../hooks/use-order-by-legacy'
+import { SortDirection } from '../../types/query-api'
 import classNames from 'classnames'
 
 export const SortButton = ({
@@ -29,8 +30,8 @@ export const SortButton = ({
           'rounded inline-block size-4',
           'ml-1',
           {
-            [SortDirection.asc]: 'rotate-180',
-            [SortDirection.desc]: 'rotate-0'
+            asc: 'rotate-180',
+            desc: 'rotate-0'
           }[sortDirection ?? next.direction],
           !sortDirection && 'opacity-0',
           !sortDirection && 'group-hover:opacity-100',

assets/js/dashboard/components/table-legacy.tsx

@@ -1,6 +1,6 @@
 import classNames from 'classnames'
 import React, { ReactNode } from 'react'
-import { SortDirection } from '../hooks/use-order-by-legacy'
+import { SortDirection } from '../../types/query-api'
 import { SortButton } from './sort-button'
 import { Tooltip } from '../util/tooltip'
 

assets/js/dashboard/current-visitors-context.tsx

@@ -0,0 +1,47 @@
+import React, { createContext, useContext, useEffect } from 'react'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { get } from './api'
+import { useSiteContext } from './site-context'
+import { useDashboardStateContext } from './dashboard-state-context'
+import { CACHE_TTL_REALTIME } from './hooks/api-client'
+import { isRealTimeDashboard } from './util/filters'
+
+const CurrentVisitorsContext = createContext<number | null>(null)
+
+export function CurrentVisitorsProvider({
+  children
+}: {
+  children: React.ReactNode
+}) {
+  const site = useSiteContext()
+  const { dashboardState } = useDashboardStateContext()
+  const queryClient = useQueryClient()
+
+  const isEnabled =
+    isRealTimeDashboard(dashboardState) || dashboardState.filters.length === 0
+
+  const { data } = useQuery<number>({
+    queryKey: ['current-visitors'],
+    queryFn: () =>
+      get(`/api/stats/${encodeURIComponent(site.domain)}/current-visitors`),
+    staleTime: CACHE_TTL_REALTIME,
+    enabled: isEnabled
+  })
+
+  useEffect(() => {
+    const onTick = () => {
+      queryClient.invalidateQueries({ queryKey: ['current-visitors'] })
+    }
+    document.addEventListener('tick', onTick)
+    return () => document.removeEventListener('tick', onTick)
+  }, [queryClient])
+
+  return (
+    <CurrentVisitorsContext.Provider value={isEnabled ? (data ?? null) : null}>
+      {children}
+    </CurrentVisitorsContext.Provider>
+  )
+}
+
+export const useCurrentVisitorsContext = () =>
+  useContext(CurrentVisitorsContext)

assets/js/dashboard/hooks/api-client.ts

@@ -13,8 +13,6 @@ import {
 } from '../dashboard-time-periods'
 import { REALTIME_UPDATE_TIME_MS } from '../util/realtime-update-timer'
 import { Interval, validIntervals } from '../stats/graph/intervals'
-import { PlausibleSite } from '../site-context'
-import { StatsQuery } from '../stats-query'
 
 // define (in ms) when query API responses should become stale
 export const CACHE_TTL_REALTIME = REALTIME_UPDATE_TIME_MS
@@ -23,7 +21,7 @@ export const CACHE_TTL_LONG_ONGOING = 60 * 60 * 1000 // 1 hour
 export const CACHE_TTL_HISTORICAL = 12 * 60 * 60 * 1000 // 12 hours
 
 // how many items per page for breakdown modals
-const PAGINATION_LIMIT = 100
+export const PAGINATION_LIMIT = 100
 
 /** full endpoint URL */
 type Endpoint = string
@@ -34,54 +32,6 @@ type GetRequestParams<TKey extends PaginatedQueryKeyBase> = (
   k: TKey
 ) => [DashboardState, Record<string, unknown>]
 
-/**
- * Hook for paginated POST /api/stats/:domain/query requests (i.e. Details views).
- */
-export function usePaginatedQueryAPI({
-  site,
-  dashboardState,
-  statsQuery
-}: {
-  site: PlausibleSite
-  dashboardState: DashboardState
-  statsQuery: StatsQuery
-}) {
-  const queryClient = useQueryClient()
-  const dimensionKey = statsQuery.dimensions.join(',')
-
-  useEffect(() => {
-    return () => {
-      const tanstackQueryFilters: QueryFilters = {
-        predicate: ({ queryKey }) => queryKey[0] === dimensionKey
-      }
-      queryClient.setQueriesData(tanstackQueryFilters, cleanToPageOne)
-    }
-  }, [queryClient, dimensionKey])
-
-  return useInfiniteQuery({
-    queryKey: [dimensionKey, statsQuery],
-    queryFn: async ({ pageParam }): Promise<api.QueryApiResponse> => {
-      return api.stats(site, {
-        ...statsQuery,
-        pagination: { limit: PAGINATION_LIMIT, offset: pageParam as number }
-      })
-    },
-    getNextPageParam: (lastPage, _, lastPageParam) => {
-      return lastPage.results.length === PAGINATION_LIMIT
-        ? (lastPageParam as number) + PAGINATION_LIMIT
-        : null
-    },
-    staleTime: () =>
-      getStaleTime({
-        siteTimezoneOffset: site.offset,
-        siteStatsBegin: site.statsBegin,
-        ...dashboardState
-      }),
-    initialPageParam: 0,
-    placeholderData: (previousData) => previousData
-  })
-}
-
 /**
  * Hook that fetches the first page from the defined GET endpoint on mount,
  * then subsequent pages when component calls fetchNextPage.

…/js/dashboard/hooks/use-order-by.test.ts …hboard/hooks/use-metric-order-by.test.tsassets/js/dashboard/hooks/use-order-by.test.ts renamed to assets/js/dashboard/hooks/use-metric-order-by.test.ts assets/js/dashboard/hooks/use-order-by.test.ts renamed to assets/js/dashboard/hooks/use-metric-order-by.test.ts

@@ -1,39 +1,38 @@
 import { Metric } from '../stats/metrics'
 import {
-  OrderBy,
-  SortDirection,
+  MetricOrderBy,
   cycleSortDirection,
   getOrderByStorageKey,
   getStoredOrderBy,
   maybeStoreOrderBy,
   rearrangeOrderBy,
   validateOrderBy
-} from './use-order-by'
+} from './use-metric-order-by'
 
 describe(`${cycleSortDirection.name}`, () => {
   test.each([
     [
       null,
       {
-        direction: SortDirection.desc,
+        direction: 'desc',
         hint: 'Press to sort column in descending order'
       }
     ],
     [
-      SortDirection.desc,
+      'desc',
       {
-        direction: SortDirection.asc,
+        direction: 'asc',
         hint: 'Press to sort column in ascending order'
       }
     ],
     [
-      SortDirection.asc,
+      'asc',
       {
-        direction: SortDirection.desc,
+        direction: 'desc',
         hint: 'Press to sort column in descending order'
       }
     ]
-  ])(
+  ] as const)(
     'for current direction %p returns %p',
     (currentDirection, expectedOutput) => {
       expect(cycleSortDirection(currentDirection)).toEqual(expectedOutput)
@@ -42,22 +41,10 @@ describe(`${cycleSortDirection.name}`, () => {
 })
 
 describe(`${rearrangeOrderBy.name}`, () => {
-  const cases: [Metric, OrderBy, OrderBy][] = [
-    [
-      'visitors',
-      [['visitors', SortDirection.asc]],
-      [['visitors', SortDirection.desc]]
-    ],
-    [
-      'visitors',
-      [['visitors', SortDirection.desc]],
-      [['visitors', SortDirection.asc]]
-    ],
-    [
-      'visit_duration',
-      [['visitors', SortDirection.asc]],
-      [['visit_duration', SortDirection.desc]]
-    ]
+  const cases: [Metric, MetricOrderBy, MetricOrderBy][] = [
+    ['visitors', [['visitors', 'asc']], [['visitors', 'desc']]],
+    ['visitors', [['visitors', 'desc']], [['visitors', 'asc']]],
+    ['visit_duration', [['visitors', 'asc']], [['visit_duration', 'desc']]]
   ]
   it.each(cases)(
     `[%#] clicking on %p yields expected order`,
@@ -96,7 +83,7 @@ describe(`storing detailed report preferred order`, () => {
 
   it('does not store invalid value', () => {
     maybeStoreOrderBy({
-      orderBy: [['total_visitors', SortDirection.desc]],
+      orderBy: [['total_visitors', 'desc']],
       domain,
       dimensionLabel,
       metrics: ['total_visitors']
@@ -108,7 +95,7 @@ describe(`storing detailed report preferred order`, () => {
 
   it('falls back to fallbackValue if metric has become unsortable between storing and retrieving', () => {
     maybeStoreOrderBy({
-      orderBy: [['visitors', SortDirection.desc]],
+      orderBy: [['visitors', 'desc']],
       domain,
       dimensionLabel,
       metrics: ['visitors']
@@ -122,13 +109,13 @@ describe(`storing detailed report preferred order`, () => {
         domain,
         dimensionLabel,
         metrics: ['total_visitors'],
-        fallbackValue: [['visitors', SortDirection.desc]]
+        fallbackValue: [['visitors', 'desc']]
       })
-    ).toEqual([['visitors', SortDirection.desc]])
+    ).toEqual([['visitors', 'desc']])
   })
 
   it('retrieves stored value correctly', () => {
-    const input: OrderBy = [['visitors', SortDirection.asc]]
+    const input: MetricOrderBy = [['visitors', 'asc']]
     localStorage.setItem(
       getOrderByStorageKey(domain, dimensionLabel),
       JSON.stringify(input)
@@ -138,7 +125,7 @@ describe(`storing detailed report preferred order`, () => {
         domain,
         dimensionLabel,
         metrics: ['visitors'],
-        fallbackValue: [['visitors', SortDirection.desc]]
+        fallbackValue: [['visitors', 'desc']]
       })
     ).toEqual(input)
   })