Extract active usage elapsed clock

frontend/src/features/usage/composables/__tests__/useActiveElapsedDisplayClock.spec.ts

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { nextTick, ref } from 'vue'
+import { useActiveElapsedDisplayClock } from '../useActiveElapsedDisplayClock'
+
+type TestRecord = {
+  status: string
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('useActiveElapsedDisplayClock', () => {
+  it('ticks only while visible active records exist', async () => {
+    vi.useFakeTimers()
+    let nowMs = 1_000
+
+    const records = ref<TestRecord[]>([])
+    const isPageVisible = ref(true)
+    const serverClockOffsetMs = ref(0)
+    const hasServerClockOffset = ref(false)
+    const clock = useActiveElapsedDisplayClock({
+      records,
+      isPageVisible,
+      serverClockOffsetMs,
+      hasServerClockOffset,
+      resolveStatus: record => record.status,
+      intervalMs: 250,
+      now: () => nowMs,
+    })
+
+    expect(clock.hasVisibleActiveRecords.value).toBe(false)
+    expect(clock.displayNowMs.value).toBe(1_000)
+
+    nowMs = 1_250
+    vi.advanceTimersByTime(250)
+    expect(clock.displayNowMs.value).toBe(1_000)
+
+    records.value = [{ status: 'streaming' }]
+    await nextTick()
+    expect(clock.hasVisibleActiveRecords.value).toBe(true)
+    expect(clock.displayNowMs.value).toBe(1_250)
+
+    nowMs = 1_500
+    vi.advanceTimersByTime(250)
+    expect(clock.displayNowMs.value).toBe(1_500)
+
+    isPageVisible.value = false
+    await nextTick()
+    nowMs = 1_750
+    vi.advanceTimersByTime(250)
+    expect(clock.displayNowMs.value).toBe(1_500)
+
+    clock.stopActiveElapsedDisplayClock()
+  })
+
+  it('applies server clock offset to the display time', () => {
+    vi.useFakeTimers()
+
+    const clock = useActiveElapsedDisplayClock({
+      records: ref<TestRecord[]>([{ status: 'pending' }]),
+      isPageVisible: ref(true),
+      serverClockOffsetMs: ref(-11_000),
+      hasServerClockOffset: ref(true),
+      resolveStatus: record => record.status,
+      intervalMs: 250,
+      now: () => 2_000,
+    })
+
+    expect(clock.calibratedDisplayNowMs.value).toBe(-9_000)
+    clock.stopActiveElapsedDisplayClock()
+  })
+
+  it('stops when active records disappear', async () => {
+    vi.useFakeTimers()
+    let nowMs = 3_000
+
+    const records = ref<TestRecord[]>([{ status: 'pending' }])
+    const clock = useActiveElapsedDisplayClock({
+      records,
+      isPageVisible: ref(true),
+      serverClockOffsetMs: ref(0),
+      hasServerClockOffset: ref(false),
+      resolveStatus: record => record.status,
+      intervalMs: 250,
+      now: () => nowMs,
+    })
+
+    nowMs = 3_250
+    vi.advanceTimersByTime(250)
+    expect(clock.displayNowMs.value).toBe(3_250)
+
+    records.value = [{ status: 'completed' }]
+    await nextTick()
+    nowMs = 3_500
+    vi.advanceTimersByTime(250)
+    expect(clock.displayNowMs.value).toBe(3_250)
+
+    clock.stopActiveElapsedDisplayClock()
+  })
+})

frontend/src/features/usage/composables/index.ts

@@ -1,4 +1,5 @@
 export { useUsageData } from './useUsageData'
+export { useActiveElapsedDisplayClock } from './useActiveElapsedDisplayClock'
 export { useUsageFilters } from './useUsageFilters'
 export { useUsagePagination } from './useUsagePagination'
 export { getDateRangeFromPeriod, formatDateTime, getSuccessRateColor } from './useDateRange'

frontend/src/features/usage/composables/useActiveElapsedDisplayClock.ts

@@ -0,0 +1,84 @@
+import { computed, ref, watch, type ComputedRef, type Ref } from 'vue'
+
+type ActiveElapsedStatus = string | null | undefined
+
+export interface UseActiveElapsedDisplayClockOptions<TRecord> {
+  records: Ref<TRecord[]> | ComputedRef<TRecord[]>
+  isPageVisible: Ref<boolean> | ComputedRef<boolean>
+  serverClockOffsetMs: Ref<number> | ComputedRef<number>
+  hasServerClockOffset: Ref<boolean> | ComputedRef<boolean>
+  resolveStatus: (record: TRecord) => ActiveElapsedStatus
+  intervalMs?: number
+  now?: () => number
+}
+
+export function useActiveElapsedDisplayClock<TRecord>(
+  options: UseActiveElapsedDisplayClockOptions<TRecord>
+) {
+  const intervalMs = options.intervalMs ?? 250
+  const now = options.now ?? Date.now
+  const displayNowMs = ref(now())
+
+  let activeElapsedDisplayTimer: ReturnType<typeof setInterval> | null = null
+
+  const hasVisibleActiveRecords = computed(() => {
+    return options.records.value.some((record) => {
+      const displayStatus = options.resolveStatus(record)
+      return displayStatus === 'pending' || displayStatus === 'streaming'
+    })
+  })
+
+  const calibratedDisplayNowMs = computed(() => {
+    return options.hasServerClockOffset.value
+      ? displayNowMs.value + options.serverClockOffsetMs.value
+      : displayNowMs.value
+  })
+
+  function tickActiveElapsedDisplay() {
+    displayNowMs.value = now()
+  }
+
+  function startActiveElapsedDisplayTimer() {
+    if (activeElapsedDisplayTimer) return
+    if (!options.isPageVisible.value || !hasVisibleActiveRecords.value) return
+    tickActiveElapsedDisplay()
+    activeElapsedDisplayTimer = setInterval(tickActiveElapsedDisplay, intervalMs)
+  }
+
+  function stopActiveElapsedDisplayTimer() {
+    if (activeElapsedDisplayTimer) {
+      clearInterval(activeElapsedDisplayTimer)
+      activeElapsedDisplayTimer = null
+    }
+  }
+
+  function syncActiveElapsedDisplayTimer() {
+    if (options.isPageVisible.value && hasVisibleActiveRecords.value) {
+      startActiveElapsedDisplayTimer()
+    } else {
+      stopActiveElapsedDisplayTimer()
+    }
+  }
+
+  const stopActiveElapsedDisplayWatch = watch(
+    [hasVisibleActiveRecords, options.isPageVisible],
+    syncActiveElapsedDisplayTimer,
+    { immediate: true }
+  )
+
+  function stopActiveElapsedDisplayClock() {
+    stopActiveElapsedDisplayWatch()
+    stopActiveElapsedDisplayTimer()
+  }
+
+  return {
+    displayNowMs,
+    calibratedDisplayNowMs,
+    hasVisibleActiveRecords,
+    tickActiveElapsedDisplay,
+    startActiveElapsedDisplayTimer,
+    stopActiveElapsedDisplayTimer,
+    syncActiveElapsedDisplayTimer,
+    stopActiveElapsedDisplayClock,
+  }
+}