@killiandvcz/superfetch

SuperFetch 🚀

A modern, lightweight, and chainable fetch library for JavaScript with built-in interceptors and middleware support.

Features ✨

• 🔗 Chainable API design
• 🎯 Powerful interceptors
• 🛠 Flexible middleware system
• ⚡️ Modern ES Modules
• 🔄 Automatic response type handling
• ⏱ Built-in timeout support
• 📦 Zero dependencies
• 🌐 Works in any JavaScript environment

Installation 📦

# Using npm
npm install @killiandvcz/superfetch

# Using yarn
yarn add @killiandvcz/superfetch

# Using pnpm
pnpm add @killiandvcz/superfetch

# Using bun
bun add @killiandvcz/superfetch

Quick Start 🚀

import SuperFetch from '@killiandvcz/superfetch';

// Create an instance with default config
const api = new SuperFetch({
  baseURL: 'https://api.example.com',
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

// Make requests
try {
  // GET request
  const users = await api.get('/users');
  
  // POST request with data
  const newUser = await api.post('/users', {
    name: 'John Doe',
    email: '[e-mail]'
  });
  
  console.log(users, newUser);
} catch (error) {
  console.error('API Error:', error);
}

Advanced Usage 🔥

Creating Multiple Instances

// Base API instance
const api = new SuperFetch({ baseURL: 'https://api.example.com' });

// User-specific instance with additional config
const userApi = api.create({
  baseURL: 'https://api.example.com/users',
  timeout: 5000
});

Using Interceptors

const api = new SuperFetch({
  // Request interceptor
  onRequest: (url, config) => {
    console.log('Making request to:', url);
    return config;
  },
  
  // Response interceptor
  onResponse: async (response) => {
    const data = await response.json();
    return data.results;
  },
  
  // Error interceptor
  onError: (error) => {
    reportError(error);
    return null;
  }
});

Adding Middleware

// Caching middleware
const cacheMiddleware = async (request) => {
  const cached = await cache.get(request.url);
  if (cached) return cached;
  return request;
};

// Logging middleware
const loggingMiddleware = async (request) => {
  console.log('Request:', request.method, request.url);
  return request;
};

// Add middlewares
api.use(cacheMiddleware)
   .use(loggingMiddleware);

File Upload

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('type', 'avatar');

await api.upload('/files', formData, {
  onProgress: (progress) => {
    console.log(`Upload progress: ${progress}%`);
  }
});

API Reference 📚

Configuration Options

Option	Type	Description	Default
baseURL	string	Base URL for all requests	''
headers	object	Default headers	{ 'Content-Type': 'application/json' }
timeout	number	Request timeout in ms	30000
credentials	string	Credentials mode	'same-origin'
onRequest	function	Request interceptor	undefined
onResponse	function	Response interceptor	undefined
onError	function	Error handler	undefined

Methods

• get(url, options)
• post(url, data, options)
• put(url, data, options)
• patch(url, data, options)
• delete(url, options)
• upload(url, formData, options)
• create(config)
• use(middleware)

Why SuperFetch? 🤔

• Modern: Built with the latest JavaScript features
• Lightweight: Zero dependencies, small bundle size
• Flexible: Powerful middleware system
• Developer-friendly: Clean, chainable API
• Type-safe: Complete JSDoc documentation
• Production-ready: Built for real-world usage

Contributing 🤝

Contributions are always welcome! Feel free to:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

Please make sure to update tests as appropriate.

License 📄

MIT © Killian Di Vincenzo