https://github.com/asouei/safe-fetch
Tiny, type-safe fetch wrapper: safe results, retries, timeouts & validation
https://github.com/asouei/safe-fetch
error-handling fetch http-client npm-package retry timeout typescript
Last synced: 29 days ago
JSON representation
Tiny, type-safe fetch wrapper: safe results, retries, timeouts & validation
- Host: GitHub
- URL: https://github.com/asouei/safe-fetch
- Owner: Asouei
- License: mit
- Created: 2025-09-01T09:51:24.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2025-09-05T08:30:49.000Z (about 1 month ago)
- Last Synced: 2025-09-08T05:02:20.988Z (29 days ago)
- Topics: error-handling, fetch, http-client, npm-package, retry, timeout, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@asouei/safe-fetch
- Size: 131 KB
- Stars: 55
- Watchers: 0
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# @asouei/safe-fetch
[](https://www.npmjs.com/package/@asouei/safe-fetch)
[](https://github.com/asouei/safe-fetch/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.npmjs.com/package/@asouei/safe-fetch)
[](https://www.typescriptlang.org/)
[](https://bundlephobia.com/package/@asouei/safe-fetch)
[](package.json)
[](https://codesandbox.io/p/sandbox/fkw3z5)
[](https://github.com/dzharii/awesome-typescript)
*English version | [Русская версия](README.ru.md)*
> **Never write `try/catch` for HTTP requests again.** A complete ecosystem of type-safe HTTP utilities built around safe results and predictable error handling.
Modern HTTP client ecosystem that eliminates exceptions through discriminated unions, provides intelligent retries, handles timeouts properly, and integrates seamlessly with popular data fetching libraries.
## 📦 Packages
| Package | Version | Description |
|---------|---------|-------------|
| **[@asouei/safe-fetch](packages/core)** | [](https://npmjs.com/package/@asouei/safe-fetch) | Core HTTP client with safe results, retries, and timeouts |
| **[@asouei/safe-fetch-react-query](packages/react-query)** | [](https://npmjs.com/package/@asouei/safe-fetch-react-query) | TanStack Query integration with optimized error handling |
## 🚀 Quick Start
```bash
npm install @asouei/safe-fetch
```
```typescript
import { safeFetch } from '@asouei/safe-fetch';
const result = await safeFetch.get<{ users: User[] }>('/api/users');
if (result.ok) {
// TypeScript knows result.data is { users: User[] }
console.log(result.data.users);
} else {
// All errors are normalized and typed
console.error(`${result.error.name}: ${result.error.message}`);
}
```
## ✨ Why safe-fetch?
- **🛡️ No Exceptions**: Never write `try/catch` — always get a safe result
- **🔧 Typed Errors**: `NetworkError | TimeoutError | HttpError | ValidationError`
- **⏱️ Smart Timeouts**: Per-attempt + total operation timeouts
- **🔄 Intelligent Retries**: Only retries safe operations + `Retry-After` support
- **📦 Zero Dependencies**: Tree-shakable, ~3kb, works everywhere
- **🧪 Validation Ready**: Built-in Zod integration without exceptions
## 📖 Documentation
- **[Core Library](packages/core/README.md)** - Complete API documentation, examples, and migration guides
- **[React Query Adapter](packages/react-query/README.md)** - TanStack Query integration
## 🌟 Core Features
### Safe Results
Every request returns a discriminated union - no more guessing what went wrong:
```typescript
type SafeResult =
| { ok: true; data: T; response: Response }
| { ok: false; error: NormalizedError; response?: Response }
```
### Normalized Errors
All errors follow the same structure:
```typescript
// Network issues, connection failures
type NetworkError = { name: 'NetworkError'; message: string; cause?: unknown }
// Request timeouts (per-attempt or total)
type TimeoutError = { name: 'TimeoutError'; message: string; timeoutMs: number }
// HTTP 4xx/5xx responses
type HttpError = { name: 'HttpError'; message: string; status: number; body?: unknown }
// Schema validation failures
type ValidationError = { name: 'ValidationError'; message: string; cause?: unknown }
```
### Smart Configuration
```typescript
import { createSafeFetch } from '@asouei/safe-fetch';
const api = createSafeFetch({
baseURL: 'https://api.example.com',
timeoutMs: 5000, // Per attempt
totalTimeoutMs: 30000, // Total operation
retries: {
retries: 2,
baseDelayMs: 300 // Exponential backoff
},
headers: { Authorization: 'Bearer token' }
});
const result = await api.get('/users');
```
## 🔮 Ecosystem Roadmap
- ✅ **Core Library** - Safe HTTP client with retries and timeouts
- ✅ **React Query Adapter** - Optimized TanStack Query integration
- 📋 **SWR Adapter** - SWR integration helpers
- 🔍 **ESLint Plugin** - Enforce safe result patterns
- 🏗️ **Framework Examples** - Next.js, Remix, Cloudflare Workers
## 📱 Framework Integration
### React Query
```typescript
import { createSafeFetch } from '@asouei/safe-fetch';
import { createQueryFn, rqDefaults } from '@asouei/safe-fetch-react-query';
const api = createSafeFetch({ baseURL: '/api' });
const queryFn = createQueryFn(api);
export function useUsers() {
return useQuery({
queryKey: ['users'],
queryFn: queryFn('/users'),
...rqDefaults() // { retry: false } - let safe-fetch handle retries
});
}
```
### Next.js / SSR
```typescript
// app/users/page.tsx
import { safeFetch } from '@asouei/safe-fetch';
export default async function UsersPage() {
const result = await safeFetch.get('/api/users');
if (!result.ok) {
return ;
}
return ;
}
```
### Cloudflare Workers
```typescript
export default {
async fetch(request: Request) {
const result = await safeFetch.get<{ status: string }>('https://api.service.com/health');
return new Response(
result.ok ? JSON.stringify(result.data) : result.error.message,
{ status: result.ok ? 200 : 500 }
);
}
};
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
**Quick development setup:**
```bash
git clone https://github.com/asouei/safe-fetch.git
cd safe-fetch
pnpm install
pnpm -r test
pnpm -r build
```
## 📄 License
MIT © [Aleksandr Mikhailishin](https://github.com/asouei)
---
**Built with ❤️ for developers who value predictable, type-safe HTTP clients.**