Рецепт: список с загрузкой из API и pull-to-refresh в React Native

{
  "items": [
    { "id": "41", "title": "Лендинг", "price": 250000 },
    { "id": "42", "title": "Интернет-магазин", "price": 900000 }
  ],
  "nextCursor": "eyJpZCI6IjQyIn0"
}

import type { Page } from '../hooks/usePagedList';

const API_URL = process.env.EXPO_PUBLIC_API_URL ?? 'https://api.example.com';
const PAGE_SIZE = 20;

export type Service = { id: string; title: string; price: number };

export class HttpError extends Error {
  constructor(public readonly status: number) {
    super(`HTTP ${status}`);
    this.name = 'HttpError';
  }
}

export async function fetchServicesPage(
  cursor: string | null,
  signal: AbortSignal,
): Promise<Page<Service>> {
  let query = `limit=${PAGE_SIZE}`;
  if (cursor) query += `&cursor=${encodeURIComponent(cursor)}`;

  const response = await fetch(`${API_URL}/v1/services?${query}`, {
    headers: { Accept: 'application/json' },
    signal,
  });
  // fetch не отклоняет промис на 404/500 — статус проверяем сами
  if (!response.ok) throw new HttpError(response.status);
  return (await response.json()) as Page<Service>;
}

import { useCallback, useEffect, useRef, useState } from 'react';

// страница ответа и курсор следующей (null — дальше пусто)
export type Page<T> = { items: T[]; nextCursor: string | null };
export type FetchPage<T> = (cursor: string | null, signal: AbortSignal) => Promise<Page<T>>;
type Mode = 'loading' | 'refreshing' | 'loadingMore';

// сервер мог сдвинуть данные между запросами — не показываем одну запись дважды
function mergeById<T extends { id: string }>(prev: T[], next: T[]): T[] {
  const seen = new Set(prev.map((item) => item.id));
  return [...prev, ...next.filter((item) => !seen.has(item.id))];
}

export function usePagedList<T extends { id: string }>(fetchPage: FetchPage<T>) {
  const [items, setItems] = useState<T[]>([]);
  const [mode, setMode] = useState<Mode | 'idle'>('loading');
  const [error, setError] = useState<unknown>(null); // первая страница или обновление
  const [moreError, setMoreError] = useState<unknown>(null); // догрузка
  const [hasMore, setHasMore] = useState(false);

  const cursorRef = useRef<string | null>(null);
  const requestRef = useRef<AbortController | null>(null);
  // синхронный флаг: два onEndReached подряд приходят раньше, чем обновится состояние
  const busyRef = useRef(false);

  const run = useCallback(
    async (next: Mode) => {
      requestRef.current?.abort(); // обновление отменяет догрузку, а не ждёт её
      const controller = new AbortController();
      requestRef.current = controller;
      busyRef.current = true;
      setMode(next);
      const append = next === 'loadingMore';

      try {
        const page = await fetchPage(append ? cursorRef.current : null, controller.signal);
        if (controller.signal.aborted) return; // устаревший ответ не перетирает новый
        setItems((prev) => (append ? mergeById(prev, page.items) : page.items));
        cursorRef.current = page.nextCursor;
        setHasMore(page.nextCursor !== null);
        setError(null);
        setMoreError(null);
      } catch (e) {
        if (controller.signal.aborted) return;
        if (append) setMoreError(e);
        else setError(e);
      } finally {
        if (requestRef.current === controller) {
          requestRef.current = null;
          busyRef.current = false;
          setMode('idle');
        }
      }
    },
    [fetchPage],
  );

  useEffect(() => {
    run('loading');
    return () => {
      requestRef.current?.abort(); // ушли с экрана — запрос больше не нужен
      requestRef.current = null;
    };
  }, [run]);

  const refresh = useCallback(() => run('refreshing'), [run]);
  const retry = useCallback(() => run('loading'), [run]);

  const loadMore = useCallback(() => {
    // после ошибки догрузки ждём кнопку «Повторить», иначе прокрутка зациклит запросы
    if (busyRef.current || cursorRef.current === null || moreError) return;
    run('loadingMore');
  }, [run, moreError]);

  const retryMore = useCallback(() => {
    setMoreError(null);
    run('loadingMore');
  }, [run]);

  return { items, mode, error, moreError, hasMore, refresh, retry, loadMore, retryMore };
}

import { memo } from 'react';
import {
  ActivityIndicator,
  Button,
  FlatList,
  StyleSheet,
  Text,
  View,
  type ListRenderItem,
} from 'react-native';
import { fetchServicesPage, HttpError, type Service } from '../api/services';
import { usePagedList } from '../hooks/usePagedList';

function errorText(e: unknown): string {
  if (e instanceof HttpError) return `Сервер ответил ошибкой ${e.status}`;
  return 'Нет соединения с сервером';
}

const ServiceRow = memo(function ServiceRow({ item }: { item: Service }) {
  return (
    <View style={styles.row} accessible>
      <Text style={styles.title}>{item.title}</Text>
      <Text style={styles.muted}>от {item.price.toLocaleString('ru-RU')} ₸</Text>
    </View>
  );
});

// вне компонента: одна и та же функция между рендерами
const renderItem: ListRenderItem<Service> = ({ item }) => <ServiceRow item={item} />;
const keyExtractor = (item: Service) => item.id;

export default function ServicesList() {
  const { items, mode, error, moreError, hasMore, refresh, retry, loadMore, retryMore } =
    usePagedList(fetchServicesPage);

  if (mode === 'loading' && items.length === 0) {
    return (
      <View style={styles.center}>
        <ActivityIndicator size="large" accessibilityLabel="Загрузка" />
        <Text style={styles.muted}>Загружаем услуги…</Text>
      </View>
    );
  }

  if (error && items.length === 0) {
    return (
      <View style={styles.center}>
        <Text style={styles.error}>{errorText(error)}</Text>
        <Button title="Повторить" onPress={retry} />
      </View>
    );
  }

  let footer = null;
  if (mode === 'loadingMore') {
    footer = <ActivityIndicator style={styles.footer} accessibilityLabel="Загружаем ещё" />;
  } else if (moreError) {
    footer = (
      <View style={styles.footer}>
        <Text style={styles.error}>Не удалось загрузить ещё: {errorText(moreError)}</Text>
        <Button title="Повторить" onPress={retryMore} />
      </View>
    );
  } else if (!hasMore && items.length > 0) {
    footer = <Text style={[styles.muted, styles.footer]}>Это все услуги</Text>;
  }

  return (
    <FlatList
      testID="services-list"
      data={items}
      renderItem={renderItem}
      keyExtractor={keyExtractor}
      ListHeaderComponent={
        error ? (
          <Text style={styles.banner}>{errorText(error)}. Показаны прежние данные</Text>
        ) : null
      }
      ListEmptyComponent={<Text style={[styles.muted, styles.footer]}>Услуг пока нет</Text>}
      ListFooterComponent={footer}
      refreshing={mode === 'refreshing'}
      onRefresh={refresh}
      onEndReached={loadMore}
      onEndReachedThreshold={0.5}
    />
  );
}

const styles = StyleSheet.create({
  center: { flex: 1, alignItems: 'center', justifyContent: 'center', gap: 12, padding: 24 },
  row: { paddingVertical: 12, paddingHorizontal: 16, borderBottomWidth: StyleSheet.hairlineWidth },
  title: { fontSize: 16, fontWeight: '600' },
  muted: { color: '#666' },
  error: { color: '#b00020', textAlign: 'center' },
  banner: { backgroundColor: '#fff4ce', padding: 12 },
  footer: { padding: 16, alignItems: 'center', gap: 8 },
});

npx create-expo-app@latest services-app --template blank-typescript
cd services-app
npx expo install react-native-safe-area-context

EXPO_PUBLIC_API_URL=https://api.example.com

import { StatusBar } from 'expo-status-bar';
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
import ServicesList from './src/screens/ServicesList';

export default function App() {
  return (
    <SafeAreaProvider>
      <SafeAreaView style={{ flex: 1 }}>
        <ServicesList />
      </SafeAreaView>
      <StatusBar style="auto" />
    </SafeAreaProvider>
  );
}

npx expo install jest-expo jest @types/jest @testing-library/react-native --dev

{
  "scripts": {
    "test": "jest"
  },
  "jest": {
    "preset": "jest-expo",
    "transformIgnorePatterns": [
      "node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|@sentry/react-native|native-base|react-native-svg)"
    ]
  }
}

{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true,
    "types": ["jest"]
  }
}

import { act, fireEvent, render, screen, userEvent } from '@testing-library/react-native';
import ServicesList from '../src/screens/ServicesList';

const items = (...ids: number[]) =>
  ids.map((n) => ({ id: String(n), title: `Услуга ${n}`, price: 10000 * n }));
const ok = (body: unknown) => ({ ok: true, status: 200, json: async () => body });

// ответ, который тест отдаёт вручную, — чтобы увидеть промежуточное состояние
function deferred() {
  let resolve!: (value: unknown) => void;
  const promise = new Promise((r) => (resolve = r));
  return { promise, resolve };
}

const fetchMock = jest.fn();
beforeEach(() => {
  fetchMock.mockReset();
  globalThis.fetch = fetchMock;
});

test('первая загрузка: индикатор, затем список', async () => {
  const first = deferred();
  fetchMock.mockReturnValueOnce(first.promise);
  await render(<ServicesList />);
  expect(screen.getByText('Загружаем услуги…')).toBeOnTheScreen();

  first.resolve(ok({ items: items(1, 2), nextCursor: null }));
  expect(await screen.findByText('Услуга 1')).toBeOnTheScreen();
  expect(screen.getByText('Это все услуги')).toBeOnTheScreen();
  expect(fetchMock.mock.calls[0][0]).toBe('https://api.example.com/v1/services?limit=20');
});

test('пустой ответ → пустое состояние', async () => {
  fetchMock.mockResolvedValueOnce(ok({ items: [], nextCursor: null }));
  await render(<ServicesList />);
  expect(await screen.findByText('Услуг пока нет')).toBeOnTheScreen();
});

test('ошибка первой загрузки → «Повторить»', async () => {
  fetchMock
    .mockRejectedValueOnce(new TypeError('Network request failed'))
    .mockResolvedValueOnce(ok({ items: items(1), nextCursor: null }));
  await render(<ServicesList />);
  expect(await screen.findByText('Нет соединения с сервером')).toBeOnTheScreen();

  await fireEvent.press(screen.getByText('Повторить'));
  expect(await screen.findByText('Услуга 1')).toBeOnTheScreen();
});

test('прокрутка до конца догружает страницу по курсору без дублей', async () => {
  fetchMock
    .mockResolvedValueOnce(ok({ items: items(1, 2, 3), nextCursor: 'c2' }))
    .mockResolvedValueOnce(ok({ items: items(3, 4, 5), nextCursor: null }));
  await render(<ServicesList />);
  await screen.findByText('Услуга 3');

  const user = userEvent.setup();
  await user.scrollTo(screen.getByTestId('services-list'), {
    y: 500,
    contentSize: { width: 400, height: 1000 },
    layoutMeasurement: { width: 400, height: 600 },
  });

  expect(await screen.findByText('Это все услуги')).toBeOnTheScreen();
  expect(fetchMock).toHaveBeenCalledTimes(2);
  expect(fetchMock.mock.calls[1][0]).toContain('cursor=c2');
  expect(screen.getAllByText('Услуга 3')).toHaveLength(1); // дубль на стыке страниц отброшен
  expect(screen.getByText('Услуга 5')).toBeOnTheScreen();
});

test('повторный onEndReached во время загрузки не шлёт второй запрос', async () => {
  const second = deferred();
  fetchMock
    .mockResolvedValueOnce(ok({ items: items(1, 2), nextCursor: 'c2' }))
    .mockReturnValueOnce(second.promise);
  await render(<ServicesList />);
  await screen.findByText('Услуга 2');

  const list = screen.getByTestId('services-list');
  await fireEvent(list, 'endReached', { distanceFromEnd: 0 });
  await fireEvent(list, 'endReached', { distanceFromEnd: 0 });
  expect(fetchMock).toHaveBeenCalledTimes(2); // первая страница + одна догрузка

  second.resolve(ok({ items: items(3), nextCursor: null }));
  expect(await screen.findByText('Услуга 3')).toBeOnTheScreen();
});

test('pull-to-refresh заменяет список, ошибка обновления сохраняет данные', async () => {
  fetchMock
    .mockResolvedValueOnce(ok({ items: items(1, 2), nextCursor: null }))
    .mockResolvedValueOnce(ok({ items: items(7), nextCursor: null }))
    .mockResolvedValueOnce({ ok: false, status: 500, json: async () => ({}) });
  await render(<ServicesList />);
  await screen.findByText('Услуга 1');

  const user = userEvent.setup();
  await user.pullToRefresh(screen.getByTestId('services-list'));
  expect(await screen.findByText('Услуга 7')).toBeOnTheScreen();
  expect(screen.queryByText('Услуга 1')).not.toBeOnTheScreen();

  await user.pullToRefresh(screen.getByTestId('services-list'));
  expect(
    await screen.findByText('Сервер ответил ошибкой 500. Показаны прежние данные'),
  ).toBeOnTheScreen();
  expect(screen.getByText('Услуга 7')).toBeOnTheScreen();
});

test('обновление отменяет догрузку, её поздний ответ не попадает в список', async () => {
  const stale = deferred();
  fetchMock
    .mockResolvedValueOnce(ok({ items: items(1), nextCursor: 'c2' }))
    .mockReturnValueOnce(stale.promise)
    .mockResolvedValueOnce(ok({ items: items(8), nextCursor: null }));
  await render(<ServicesList />);
  await screen.findByText('Услуга 1');

  const list = screen.getByTestId('services-list');
  await fireEvent(list, 'endReached', { distanceFromEnd: 0 });
  const user = userEvent.setup();
  await user.pullToRefresh(list);
  expect(await screen.findByText('Услуга 8')).toBeOnTheScreen();
  expect(fetchMock.mock.calls[1][1].signal.aborted).toBe(true);

  await act(async () => {
    stale.resolve(ok({ items: items(99), nextCursor: null })); // ответ пришёл после отмены
  });
  expect(screen.queryByText('Услуга 99')).not.toBeOnTheScreen();
});

test('ошибка догрузки: кнопка в подвале, прокрутка не повторяет запрос сама', async () => {
  fetchMock
    .mockResolvedValueOnce(ok({ items: items(1), nextCursor: 'c2' }))
    .mockRejectedValueOnce(new TypeError('Network request failed'))
    .mockResolvedValueOnce(ok({ items: items(2), nextCursor: null }));
  await render(<ServicesList />);
  await screen.findByText('Услуга 1');

  const list = screen.getByTestId('services-list');
  await fireEvent(list, 'endReached', { distanceFromEnd: 0 });
  expect(
    await screen.findByText('Не удалось загрузить ещё: Нет соединения с сервером'),
  ).toBeOnTheScreen();
  await fireEvent(list, 'endReached', { distanceFromEnd: 0 });
  expect(fetchMock).toHaveBeenCalledTimes(2); // ждём явного «Повторить»

  await fireEvent.press(screen.getByText('Повторить'));
  expect(await screen.findByText('Услуга 2')).toBeOnTheScreen();
});

test('уход с экрана отменяет запрос', async () => {
  fetchMock.mockReturnValueOnce(new Promise(() => {}));
  await render(<ServicesList />);
  const { signal } = fetchMock.mock.calls[0][1] as { signal: AbortSignal };
  expect(signal.aborted).toBe(false);

  await screen.unmount();
  expect(signal.aborted).toBe(true);
});

$ npx tsc --noEmit
$ npx jest --verbose
PASS __tests__/ServicesList.test.tsx
  √ первая загрузка: индикатор, затем список (406 ms)
  √ пустой ответ → пустое состояние (4 ms)
  √ ошибка первой загрузки → «Повторить» (26 ms)
  √ прокрутка до конца догружает страницу по курсору без дублей (82 ms)
  √ повторный onEndReached во время загрузки не шлёт второй запрос (62 ms)
  √ pull-to-refresh заменяет список, ошибка обновления сохраняет данные (31 ms)
  √ обновление отменяет догрузку, её поздний ответ не попадает в список (15 ms)
  √ ошибка догрузки: кнопка в подвале, прокрутка не повторяет запрос сама (6 ms)
  √ уход с экрана отменяет запрос
Tests:       9 passed, 9 total
$ npx expo export --platform android --platform ios
iOS Bundled 3557ms index.ts (590 modules)
Android Bundled 5466ms index.ts (592 modules)
Exported: dist
$ npx expo-doctor
21/21 checks passed. No issues detected!