nitro-fetch

Nano Fetch

A lightweight HTTP client library inspired by Axios, built with TypeScript.

Features

• Promise-based API
• Request and response interceptors
• Automatic JSON data transformation
• Request timeout support
• TypeScript support
• Configurable base URL
• Query parameter handling
• Custom headers support
• Endpoints registration

Installation

npm install nano-fetch

Usage

Basic Usage

import { create } from 'nano-fetch';

const api = create({
  baseURL: 'https://api.example.com',
  headers: {
    'Authorization': 'Bearer token'
  }
});

// GET request
const response = await api.get('/users');

// POST request
const newUser = await api.post('/users', {
  name: 'John Doe',
  email: '[e-mail]'
});

// PUT request
const updatedUser = await api.put('/users/1', {
  name: 'John Smith'
});

// DELETE request
await api.delete('/users/1');

Named Endpoints

You can register and call endpoints by name:

import { create } from 'nano-fetch';

const api = create({
  baseURL: 'https://api.example.com'
});

// Register a single endpoint
api.registerEndpoint('getUser', {
  method: 'GET',
  path: '/users/:id',
  config: {
    params: { include: 'profile' }
  }
});

// Register multiple endpoints at once
api.registerEndpoints({
  createUser: {
    method: 'POST',
    path: '/users',
    config: {
      headers: { 'Content-Type': 'application/json' }
    }
  },
  updateUser: {
    method: 'PUT',
    path: '/users/:id'
  }
});

// Call endpoints by name
const user = await api.call('getUser', null, { params: { id: 123 } });
const newUser = await api.call('createUser', {
  name: 'John Doe',
  email: '[e-mail]'
});
const updatedUser = await api.call('updateUser', {
  name: 'John Smith'
}, { params: { id: 123 } });

Interceptors

You can add request and response interceptors to modify requests or responses:

// Add a request interceptor
api.interceptors.request.use(
  (config) => {
    // Modify the request config
    config.headers['X-Custom-Header'] = 'value';
    return config;
  },
  (error) => {
    // Handle request error
    return Promise.reject(error);
  }
);

// Add a response interceptor
api.interceptors.response.use(
  (response) => {
    // Modify the response
    response.data.customField = 'value';
    return response;
  },
  (error) => {
    // Handle response error
    return Promise.reject(error);
  }
);

// Remove an interceptor
const requestInterceptorId = api.interceptors.request.use(/* ... */);
api.interceptors.request.eject(requestInterceptorId);

// Clear all interceptors
api.interceptors.request.clear();
api.interceptors.response.clear();

Configuration

You can configure the client with the following options:

const api = create({
  baseURL: 'https://api.example.com',
  headers: {
    'Content-Type': 'application/json'
  },
  timeout: 5000, // 5 seconds
  params: {
    api_key: 'your-api-key'
  },
  retry: {
    count: 3, // Number of retry attempts
    delay: 1000, // Delay between retries in milliseconds
    shouldRetry: (error) => {
      // Only retry on network errors or 5xx status codes
      return error.message.includes('Network') || 
             (error.response?.status >= 500 && error.response?.status < 600);
    },
    onRetry: (error, attempt) => {
      console.log(`Retry attempt ${attempt} after error: ${error.message}`);
    }
  }
});

Retry Configuration

The retry configuration allows you to handle transient failures automatically:

// Global retry configuration
const api = create({
  retry: {
    count: 3,
    delay: 1000
  }
});

// Per-request retry configuration
const response = await api.get('/users', {
  retry: {
    count: 5,
    delay: 2000,
    shouldRetry: (error) => {
      // Custom retry logic
      return error.message.includes('timeout');
    },
    onRetry: (error, attempt) => {
      console.log(`Retrying request (attempt ${attempt})`);
    }
  }
});

// Named endpoint with retry configuration
api.registerEndpoint('getUser', {
  method: 'GET',
  path: '/users/:id',
  config: {
    retry: {
      count: 2,
      delay: 500
    }
  }
});

The retry configuration supports:

• count: Number of retry attempts (default: 0)
• delay: Delay between retries in milliseconds (default: 1000)
• shouldRetry: Function to determine if a request should be retried (default: retry on all errors)
• onRetry: Callback function called before each retry attempt

API Reference

Methods

• get(url: string, config?: RequestConfig)
• post(url: string, data?: any, config?: RequestConfig)
• put(url: string, data?: any, config?: RequestConfig)
• delete(url: string, config?: RequestConfig)
• patch(url: string, data?: any, config?: RequestConfig)
• executeCollection(collection: ApiCollection, options?: BatchRequestOptions)

Response Structure

interface Response<T> {
  data: T;
  status: number;
  statusText: string;
  headers: Record<string, string>;
  config: RequestConfig;
}

License

MIT