Safe-fetch 1.0: от библиотеки к экосистеме за 72 часа

Три дня назад я опубликовал статью про safe-fetch — библиотеку, которая убирает try/catch из HTTP-запросов. Вчера статья набрала 8,5K просмотров и 64 добавления в закладки. А сегодня представляю safe-fetch 1.0 — уже не просто библиотеку, а целую экосистему.

Ссылка на первую статью

История о том, как фидбек сообщества за 72 часа превратил обертку над fetch в полноценную платформу для типобезопасного HTTP.

Как всё началось

1 сентября выпустил safe-fetch 0.1.0 и написал статью. Идея простая: вместо try/catch везде — безопасные результаты с типизированными ошибками.

// Было try {   const res = await fetch('/users');   if (!res.ok) throw new Error(`HTTP ${res.status}`);   const data = await res.json(); } catch (e) {   console.error('Что-то сломалось:', e.message); }  // Стало const result = await safeFetch.get<User[]>('/users'); if (result.ok) {   console.log(result.data); } else {   console.error(result.error.name); // NetworkError | TimeoutError | HttpError } 

4 сентября статья вышла на Хабре. 5 сентября — сегодня — выпускаю 1.0 с экосистемой.

Что произошло за три дня

Статистика взорвалась

• 8,5K просмотров за первые сутки

• 64 добавления в закладки

• 30 звезд на GitHub

• 70 скачиваний с NPM

• 2 пулл-реквеста от сообщества

• Попадание в Awesome TypeScript

Фидбек показал направление

Комментарии были конкретными:

• «Как интегрировать с React Query?»

• «А для SWR будет?»

• «Можно ли это организовать как монорепо?»

• «Нужен ESLint plugin для проверки { ok }»

Стало понятно: одной библиотеки недостаточно. Нужна экосистема.

Safe-fetch 1.0: стабилизация

Первое изменение — переход на версию 1.0.0. Не новые фичи, а стабилизация архитектуры:

Монорепо структура

Переезд в workspace для управления несколькими пакетами:

packages/ ├── core/                 # @asouei/safe-fetch   └── react-query/          # @asouei/safe-fetch-react-query 

Современный стек

• Vite + Vitest вместо custom build

• GitHub Actions для всех пакетов сразу

• ESM/CJS экспорты улучшены

Zero breaking changes

Весь существующий код работает без изменений:

const result = await safeFetch.get('/api/data'); // Точно так же, как в 0.1.0 

Новинка: React Query адаптер

Самый частый вопрос касался React Query. Проблема понятна: React Query ожидает throws, safe-fetch возвращает { ok: false }.

Проблема в деталях

В React Query принято бросать ошибки для их обработки:

const { data, error } = useQuery({   queryFn: async () => {     const response = await fetch('/users');     if (!response.ok) throw new Error('Failed');     return response.json();   } }); 

С safe-fetch приходилось делать unwrap вручную:

const { data, error } = useQuery({   queryFn: async () => {     const result = await safeFetch.get<User[]>('/users');     if (!result.ok) throw result.error; // каждый раз вручную     return result.data;   },   retry: false // не забыть отключить }); 

Решение: адаптер

Встречайте @asouei/safe-fetch-react-query@0.1.0:

npm install @asouei/safe-fetch-react-query 

import { createQueryFn, rqDefaults } from '@asouei/safe-fetch-react-query';  const queryFn = createQueryFn(api);  const { data, error } = useQuery({   queryKey: ['users'],   queryFn: queryFn<User[]>('/users'),   ...rqDefaults() // { retry: false } + другие настройки });  // error теперь typed: NetworkError | HttpError | TimeoutError | ValidationError 

Что дает адаптер

1. Автоматический unwrap: { ok: false } → throw error

2. Сохранение типизации: TypeScript знает тип ошибки в React Query

3. Фабричные функции: createQueryFn, createMutationFn

4. Умные дефолты: rqDefaults() отключает дублирующие ретраи

Сравнение до и после

Раньше: boilerplate в каждом хуке

function useUsers() {   return useQuery({     queryKey: ['users'],     queryFn: async () => {       const result = await safeFetch.get<User[]>('/users');       if (!result.ok) throw result.error; // копипаста       return result.data;     },     retry: false // можно забыть   }); }  function useCreateUser() {   return useMutation({     mutationFn: async (data: NewUser) => {       const result = await safeFetch.post<User>('/users', data);       if (!result.ok) throw result.error; // опять       return result.data;     }   }); } 

Теперь: фабрики решают все

const api = createSafeFetch({ baseURL: '/api' }); const queryFn = createQueryFn(api); const mutationFn = createMutationFn(api);  function useUsers() {   return useQuery({     queryKey: ['users'],     queryFn: queryFn<User[]>('/users'),     ...rqDefaults()   }); }  function useCreateUser() {   return useMutation({     mutationFn: mutationFn<User>('/users', { method: 'POST' })   }); } 

Результат: 45 строк unwrap кода → 0 строк. Время рефакторинга: 20 минут.

История из production

Тестировал адаптер на реальном проекте. Было 15 хуков с React Query, каждый с одинаковым unwrap паттерном.

Проблемы до адаптера:

• 8 раз забыл retry: false — получал двойные ретраи

• 3 раза TypeScript не поймал ошибку типизации

• 45 строк дублирующегося кода

После внедрения:

• 0 забытых настроек — rqDefaults() всегда одинаковые

• Полная типизация ошибок работает из коробки

• Вся логика в фабриках — единая точка истины

Что значит экосистема

Safe-fetch больше не просто библиотека. Это платформа для типобезопасного HTTP:

Принципы экосистемы

1. Модульность: каждый адаптер — отдельный пакет

2. Типобезопасность: TypeScript first во всем

3. Zero config: работает из коробки с умными дефолтами

4. Обратная совместимость: апдейты не ломают код

Сравнение с конкурентами

Quick start с экосистемой

Установка

npm install @asouei/safe-fetch @asouei/safe-fetch-react-query 

Настройка API

import { createSafeFetch } from '@asouei/safe-fetch'; import { createQueryFn, createMutationFn, rqDefaults } from '@asouei/safe-fetch-react-query';  const api = createSafeFetch({   baseURL: '/api',   timeoutMs: 5000,   retries: { retries: 2 } });  const queryFn = createQueryFn(api); const mutationFn = createMutationFn(api); 

Использование в компонентах

function UserProfile({ userId }: { userId: string }) {   const { data: user, error, isLoading } = useQuery({     queryKey: ['user', userId],     queryFn: queryFn<User>(`/users/${userId}`),     ...rqDefaults()   });    const updateUser = useMutation({     mutationFn: mutationFn<User>(`/users/${userId}`, { method: 'PUT' })   });    if (isLoading) return <div>Loading...</div>;   if (error) {     // error typed as NetworkError | HttpError | TimeoutError | ValidationError     return <div>Error: {error.name} - {error.message}</div>;   }    return (     <div>       <h1>{user?.name}</h1>       <button onClick={() => updateUser.mutate({ name: 'New Name' })}>         Update       </button>     </div>   ); } 

Roadmap экосистемы

Stage 1 2025: расширение интеграций

• SWR адаптер — аналогично React Query (0.x experimental)

• Next.js стартер — готовый шаблон проекта

• Cloudflare Workers примеры — для edge computing

Stage 2 2025: dev tools

• ESLint plugin — правила для паттерна { ok }

• VS Code extension — сниппеты и автодополнение

• Chrome DevTools — инспектирование safe-fetch запросов

Stage 3 2025: продвинутые фичи

• OpenAPI генератор — typed клиенты из схем

• GraphQL мост — safe results для GraphQL

• Request deduplication — автоматическая дедупликация запросов

Отзывы сообщества

За первый день собрался интересный фидбек:

«Надо будет «потыкать», так как хочется предложить альтернативу axios’у в проектах.» — техлид из e-commerce

«Попробовал на pet проекте. Больше не хочу возвращаться к обычному fetch» — фронтенд разработчик

Для кого эта экосистема

Команды на React Query + TypeScript

Если уже используете TanStack React Query и цените типизацию — адаптер решает все проблемы интеграции.

Проекты с жесткими SLA

Комбинация safe-fetch (надежные таймауты + ретраи) + React Query (кеширование) = bulletproof архитектура.

Растущие команды

Фабричный подход унифицирует HTTP в команде. Джуниоры физически не смогут написать неправильный код.

Заключение: от идеи до экосистемы

За 72 часа произошла эволюция:

• 1 сентября: идея и релиз 0.1.0

• 4 сентября: статья на Хабре, фидбек сообщества

• 5 сентября: экосистема 1.0 с React Query адаптером

Safe-fetch core 1.0 стабилен и готов к production. React Query adapter 0.1 — экспериментальный, но уже снимает весь unwrap-бойлерплейт. Попробуйте, киньте фидбек в Issues и поставьте звезду на GitHub — это реально помогает проекту расти.

Следующая статья будет про SWR адаптер. Подписывайтесь на эволюцию экосистемы в реальном времени.

---

Ссылки:

• GitHub экосистемы

• Core документация

• React Query адаптер

• NPM: @asouei/safe-fetch

• NPM: @asouei/safe-fetch-react-query