Skip to content

armgit / lyftr

Public Imported from GitHub
0

Self-hosted fitness tracker. Log workouts, track nutrition, and monitor progress. Docker deployment, mobile-friendly.

9.2 KB
Raw Blame
// Offset-paginated list state against a server fetcher, shared by both apps.
//
// Pagination is driven by an explicit loadMore() rather than a scroll sentinel, because
// the trigger is the one genuinely platform-specific part: React Native wires it to
// FlatList onEndReached, the web wraps this with an IntersectionObserver (see
// web/src/hooks/useServerInfiniteList.ts).
//
// Two behaviours here that web's own copy lacked before this moved:
//
//  - A monotonic request id. Responses that do not match the latest id are dropped, so a
//    slow request for an old query ("a") cannot overwrite the results of a newer one
//    ("ab") when they resolve out of order — the classic search race. Web had no guard
//    at all, so typing quickly could leave stale results on screen for good.
//  - Rejections are caught. Web let them escape, which is merely noisy in a browser but
//    a red box on RN; either way the list now keeps what loaded and stops paginating.
//
// Neither reload() nor a deps change hard-clears the list: both refetch page 0 and swap
// the results in place, so the list never flashes empty while typing a query or after a
// delete. `refreshing` marks the deps-change case so a screen can show a subtle cue over
// the stale results.
import { useState, useEffect, useRef, useCallback } from 'react'
import { apiErrorMessage } from '../client'
import { useTranslation } from '../i18n'

interface Options<T> {
  fetcher: (offset: number, limit: number) => Promise<T[]>
  pageSize?: number
  // Changing any dep resets the list and re-fetches from offset 0 (e.g. search query).
  // Compared with Object.is, so pass primitives or stable references: a fresh object or
  // array each render reads as a change every render, which keeps hasMore true and
  // refetches page 0 every render.
  deps?: readonly unknown[]
  // Shown when the server gives us nothing better to say. Pass it translated, at render.
  errorFallback?: string
}

interface Result<T> {
  items: T[]
  // Wire to FlatList onEndReached — no-ops while a fetch is in flight or when done.
  loadMore: () => void
  hasMore: boolean
  loading: boolean
  // True only during the very first fetch — use for the initial spinner
  initialLoading: boolean
  // True while a deps change (e.g. a new search query) is re-fetching page 0 with the
  // previous results still on screen — drive a subtle "searching" indicator with this.
  refreshing: boolean
  // Background revalidate: refetch page 0 and swap in place (keeps current items
  // visible meanwhile). Call on focus / after a mutation without an empty flash.
  // Background revalidate; returns the fetch promise so a caller (e.g. pull-to-refresh)
  // can await completion to drive its own spinner.
  reload: () => Promise<void>
  // Why the last fetch failed, or null. A page that never arrived used to just set
  // hasMore=false, so the list stopped exactly like a list that had reached its end —
  // the one shape a reader cannot tell from success. Render it, with retry().
  error: string | null
  // The rows on screen are from an earlier query: a new query's first page failed, and the old
  // rows are kept rather than blanked. Dim them and say so, or they read as the answer to the
  // search or filter just made. False when a later page failed (the rows are still the answer).
  staleResults: boolean
  // Resume from wherever we stopped. Keeps whatever already loaded.
  retry: () => void
}

export function useServerList<T>({
  fetcher,
  pageSize = 20,
  deps = [],
  errorFallback,
}: Options<T>): Result<T> {
  const { t } = useTranslation()
  const [items, setItems] = useState<T[]>([])
  const [hasMore, setHasMore] = useState(true)
  const [loading, setLoading] = useState(false)
  const [refreshing, setRefreshing] = useState(false)
  // What failed, not what to say about it: the sentence is made at render so it follows a
  // language switch. `unreadable` is a 200 with a body that is not a list; `cause` is a
  // rejected fetch.
  const [failure, setFailure] = useState<(({ unreadable: true } | { cause: unknown }) & { firstPage: boolean }) | null>(null)
  const offsetRef = useRef(0)
  // Tracks whether a fetch is in flight to prevent double-fetches (onEndReached can
  // fire repeatedly during momentum scrolling)
  const fetchingRef = useRef(false)
  // Flips true after first fetch settles — never resets — drives initialLoading
  const initializedRef = useRef(false)
  // Monotonic id stamped on each fetch. Responses that don't match the latest id are
  // ignored, so a slow request for an old query (e.g. "a") can't overwrite the results
  // of a newer one ("ab") when they resolve out of order — the classic search race.
  const reqIdRef = useRef(0)
  const appliedDepsRef = useRef(deps)

  const fetchPage = useCallback(async (currentOffset: number, replace: boolean) => {
    if (fetchingRef.current) return
    fetchingRef.current = true
    const myId = ++reqIdRef.current
    setLoading(true)
    try {
      const page = await fetcher(currentOffset, pageSize)
      if (myId !== reqIdRef.current) return // superseded by a newer fetch — drop it
      // A response that is not a list takes the whole app down, not just this list:
      // the spread below throws, React unmounts the tree, and with no error boundary
      // anywhere the screen goes white — no nav, nothing to click, dead until a manual
      // reload. Measured with {"data": null} and with {} from a stubbed endpoint, which
      // is what a half-deployed backend or a proxy in front of the wrong service sends.
      //
      // Reported as a failure rather than coerced to []: an empty array here would draw
      // "No workouts found", which is the same lie about the user's data that the rest
      // of this work exists to remove.
      if (!Array.isArray(page)) {
        if (myId === reqIdRef.current) {
          setHasMore(false)
          setFailure({ unreadable: true, firstPage: replace })
        }
        return
      }
      setFailure(null)
      setItems(prev => (replace ? page : [...prev, ...page]))
      offsetRef.current = currentOffset + page.length
      setHasMore(page.length === pageSize)
    } catch (err) {
      // Web lets rejections escape (harmless in a browser); on RN an unhandled
      // rejection is red-box noise — keep what loaded and stop paginating instead.
      //
      // Stopping quietly was the whole bug: hasMore=false renders exactly like
      // reaching the end of the data, so a dropped connection looked like "that is
      // all there is". Name it and let the screen offer retry().
      if (myId === reqIdRef.current) {
        setHasMore(false)
        setFailure({ cause: err, firstPage: replace })
      }
    } finally {
      // Only the latest fetch owns the shared flags — a stale response bows out without
      // flipping loading/fetching out from under the request that superseded it.
      if (myId === reqIdRef.current) {
        initializedRef.current = true
        fetchingRef.current = false
        setLoading(false)
      }
    }
  }, [fetcher, pageSize])

  // Deps change (e.g. the search query): reset pagination and refetch page 0, but keep
  // the previous results on screen until the fresh page replaces them (stale-while-
  // revalidate) so the list/summary never flash to empty. `refreshing` drives the
  // screen's "searching" cue over the stale list; it clears when the fetch settles.
  useEffect(() => {
    appliedDepsRef.current = deps
    offsetRef.current = 0
    setHasMore(true)
    setFailure(null)
    fetchingRef.current = false
    setRefreshing(true)
    fetchPage(0, true).finally(() => setRefreshing(false))
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [...deps])

  const loadMore = useCallback(() => {
    if (!hasMore || fetchingRef.current) return
    fetchPage(offsetRef.current, false)
  }, [hasMore, fetchPage])

  // Soft/background reload: fetchPage(0, replace) swaps the fresh page in on arrival
  // without a preceding setItems([]) — no empty flash. offset/hasMore are reset by
  // the fetch itself on success.
  const reload = useCallback(() => fetchPage(0, true), [fetchPage])

  // Resume, rather than reload: the pages already on screen are fine, it was the next
  // one that never came. hasMore has to go back up first — loadMore checks it, and the
  // failure is what set it false.
  const retry = useCallback(() => {
    setFailure(null)
    setHasMore(true)
    fetchPage(offsetRef.current, offsetRef.current === 0)
  }, [fetchPage])

  // The reset above runs after the render that saw the new deps, so that one render
  // still carries the previous query's hasMore. A caller reading "settled" from it
  // would answer for a query nobody asked any more; a change of deps means unsettled.
  const depsPending = deps.length !== appliedDepsRef.current.length
    || deps.some((d, i) => !Object.is(d, appliedDepsRef.current[i]))

  const error = failure === null ? null
    : 'cause' in failure ? apiErrorMessage(failure.cause, errorFallback ?? t('errors.list.loadFailed'))
      : t('errors.list.unreadable')

  return {
    items, loadMore, hasMore: hasMore || depsPending, loading,
    initialLoading: loading && !initializedRef.current,
    refreshing, reload, error, retry,
    staleResults: failure !== null && failure.firstPage && items.length > 0,
  }
}