turfetch

📖 Turfetch - A Boosted Fetch API

🚀 Turfetch is a lightweight, feature-rich wrapper around the native fetch API, providing:

• Automatic error handling 🛑
• Built-in timeouts ⏳
• Retry logic 🔄
• Query string support with urlchemy 🔗
• Base URL configuration 🌍
• TypeScript support ✅

---

📦 Installation

Install via npm or yarn:

npm install turfetch
# or
yarn add turfetch

---

🚀 Quick Start

Creating a Turfetch instance

You can create an instance with a base URL for convenient API calls.

import { createTurfetch } from 'turfetch';

const api = createTurfetch({ baseUrl: 'https://jsonplaceholder.typicode.com' });

async function fetchPosts() {
  try {
    const posts = await api.get('/posts');
    console.log(posts);
  } catch (error) {
    console.error(error);
  }
}

fetchPosts();

---

🌟 Features

1. Automatic Error Handling

If the request fails (e.g., 404 or 500 status), an error is thrown.

try {
  const user = await api.get('/invalid-endpoint');
} catch (error) {
  console.error(error); // Logs: "HTTP error: 404 Not Found"
}

---

2. Built-in Timeouts

Requests will automatically abort if they exceed the specified timeout.

try {
  const data = await api.get('/slow-endpoint', { timeout: 5000 }); // Timeout in 5s
} catch (error) {
  console.error(error); // Logs: "Request timed out"
}

---

3. Retry Logic

You can configure the number of retries and an optional retry callback.

const response = await api.get('/unstable-endpoint', {
  retry: 3,
  onRetry: (attempt) => console.log(`Retry attempt: ${attempt}`),
});

Example output:

Retry attempt: 1
Retry attempt: 2
Retry attempt: 3

---

4. Query Parameters Support

Using urlchemy, query parameters are automatically formatted.

const data = await api.get('/users', { query: { id: 42, name: 'John Doe' } });
// Makes request: GET /users?id=42&name=John%20Doe

---

5. Flexible Request Methods

Turfetch supports GET, POST, PUT, and DELETE methods.

const newUser = await api.post('/users', {
  body: { name: 'John Doe', age: 30 },
});

---

🔧 API Reference

createTurfetch({ baseUrl?: string }): TurfetchInstance

Creates a new Turfetch instance with an optional base URL.

Methods:

Method	Description
get(endpoint: string, options?: TurfetchOptions)	Performs a GET request
post(endpoint: string, options?: TurfetchOptions)	Performs a POST request
put(endpoint: string, options?: TurfetchOptions)	Performs a PUT request
delete(endpoint: string, options?: TurfetchOptions)	Performs a DELETE request

---

📌 Roadmap (Future Features)

✅ Current Features:

• [x] Error handling
• [x] Timeout support
• [x] Retry mechanism
• [x] Query parameters

🚀 Planned Features:

• [ ] Custom Error Handling Hooks (define error-handling callbacks)
• [ ] Progress Tracking (track upload/download progress)
• [ ] Request Cancellation (manually cancel an ongoing request)

---

📜 License

MIT © 2025 Thomas Toledo-Pierre

---

Would you like to extend Turfetch further? Feel free to contribute! 🚀