freq ⚡

Fast Request — HTTP client yang ringan, cepat, dan modern untuk Node.js & browser.

Dibangun dari analisis mendalam terhadap axios dan node:http:

• Performa tinggi dengan native node:http/https + fetch adapter

Instalasi

npm install freq-http

Quick Start

const freq = require('freq-http');

// GET request
const res = await freq.get('https://api.example.com/users');
console.log(res.data);

// POST request
const res = await freq.post('https://api.example.com/users', {
  name: 'xai',
  role: 'dev'
});

API Reference

HTTP Methods

freq.get(url, config?)
freq.post(url, data?, config?)
freq.put(url, data?, config?)
freq.patch(url, data?, config?)
freq.delete(url, config?)
freq.head(url, config?)
freq.options(url, config?)

Konfigurasi

const res = await freq({
  url: 'https://api.example.com/data',
  method: 'post',
  baseURL: 'https://api.example.com',
  headers: { 'X-Custom': 'value' },
  params: { page: 1 },
  data: { foo: 'bar' },
  timeout: 5000,
  responseType: 'json',          // 'json' | 'text' | 'blob' | 'arraybuffer' | 'stream'
  validateStatus: (s) => s < 500,
  maxRedirects: 5,

  // Retry otomatis
  retry: {
    retries: 3,
    factor: 2,
    minTimeout: 100,
    maxTimeout: 5000,
    retryOn: [429, 500, 502, 503, 504],
  },

  // Cache response (GET/HEAD only)
  cache: {
    ttl: 60000,   // 1 menit
    maxSize: 100,
  },
});

Instance Custom

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

const res = await api.get('/users');

Interceptors

// Request interceptor
freq.interceptors.request.use(config => {
  config.headers.set('X-Timestamp', Date.now().toString());
  return config;
});

// Response interceptor
freq.interceptors.response.use(
  response => response,
  error => {
    if (error.response?.status === 401) {
      // handle unauthorized
    }
    return Promise.reject(error);
  }
);

Cancellation

// Via CancelToken (axios-compatible)
const { token, cancel } = freq.CancelToken.source();

freq.get('/slow-endpoint', { cancelToken: token });
cancel('Dibatalkan user');

// Via AbortController (native)
const controller = new AbortController();
freq.get('/endpoint', { signal: controller.signal });
controller.abort();

Retry

const res = await freq.get('https://api.unstable.com/data', {
  retry: {
    retries: 3,
    retryOn: [429, 500, 503],
    retryNetworkErrors: true,
    onRetry: (attempt, err) => console.log(`Retry ${attempt}`, err.message),
  }
});

Caching

// Enable built-in LRU cache
const api = freq.create({ cache: true });

// Custom TTL
const api = freq.create({
  cache: { ttl: 30000, maxSize: 50 }
});

// Invalidate manual
api.cache.invalidate('/users');
api.cache.clear();

FreqHeaders

const { FreqHeaders } = require('freq');

const headers = new FreqHeaders({
  'content-type': 'application/json',
  'accept': 'application/json',
});

headers.set('authorization', 'Bearer TOKEN');
headers.get('content-type'); // 'application/json'
headers.has('accept');       // true
headers.toObject();          // plain object

Error Handling

try {
  await freq.get('/endpoint');
} catch (err) {
  if (freq.isFreqError(err)) {
    console.log(err.response?.status);  // HTTP status
    console.log(err.code);              // ERR_NETWORK, ECONNABORTED, dll
    console.log(err.config.url);
  }
}

Error Codes

| Kode | Deskripsi | |------|-----------| | ERR_NETWORK | Network failure | | ECONNABORTED | Timeout | | ERR_CANCELED | Request dibatalkan | | ERR_BAD_REQUEST | Request tidak valid | | ERR_BAD_RESPONSE | Response tidak bisa diparsing | | ERR_INVALID_URL | URL tidak valid |

Concurrent Requests

const [users, posts] = await freq.all([
  freq.get('/users'),
  freq.get('/posts'),
]);

Adapters

freq memilih adapter otomatis berdasarkan environment:

| Environment | Adapter | |-------------|---------|

| Browser / Edge | fetch |

Override manual:

freq.get('/data', { adapter: 'fetch' });

Arsitektur

freq/
├── index.js              # Entry point + default instance
├── index.d.ts            # TypeScript definitions
└── lib/
    ├── freq.js           # Core Freq class
    ├── adapters/
    │   ├── index.js      # Adapter resolver
    │   ├── http.js       # Node.js (native http/https)
    │   └── fetch.js      # Browser/Edge (fetch)
    ├── cache/
    │   └── index.js      # LRU cache + cache-control parser
    ├── core/
    │   ├── Headers.js        # Case-insensitive headers
    │   ├── FreqError.js      # Error class
    │   ├── InterceptorManager.js
    │   ├── dispatchRequest.js
    │   └── mergeConfig.js
    ├── handler/
    │   ├── CancelToken.js    # Cancellation
    │   ├── retry.js          # Exponential backoff retry
    │   └── timeout.js        # AbortSignal timeout
    └── utils/
        └── index.js          # Internal utilities

License

MIT