@qbit-labs/super-axios

A lightweight wrapper around Axios with server-side caching backed by Redis. Designed for Node services and enterprise workloads where a single authoritative cache (Redis) is preferred.

✨ Features

• ⚡ Drop-in replacement for Axios (all axios features still available)
• 📦 Smart caching: caches responses automatically by URL + payload
• 🔑 Custom cache keys for finer control
• 🗄️ Storage: Redis (server-side)
• ⏱️ Configurable stale times: control how long cached data stays fresh
• 🚀 Works with GET, POST, DELETE, PUT, etc.

📊 Performance Benchmark

Super-Axios drastically improves response times on repeated requests compared to raw Axios.

| Network Speed | Without Cache (Axios) | With Cache (Super-Axios) | Improvement | |---------------|------------------------|---------------------------|-------------| | Fast 4G | ~250ms | ~20ms | 🚀 ~92% faster | | 3G | ~1200ms | ~30ms | 🚀 ~97% faster | | Slow Internet (1Mbps) | ~3000ms | ~50ms | 🚀 ~98% faster |

Key Notes

• Without cache → Every request goes to the server, causing delays especially on slower networks.
• With cache → Subsequent requests for the same key are served instantly from Redis cache.
• Use Case: Ideal for apps where repeated data fetching occurs (e.g., user profiles, product lists).

📦 Installation

pnpm install @qbit-labs/super-axios

Or with npm/yarn:

npm install @qbit-labs/super-axios
# or
yarn add @qbit-labs/super-axios

⚙️ Usage (server / Node)

import axios from "axios";
import { createSuperAxios } from "@qbit-labs/super-axios";

// Create a super-axios instance backed by Redis
const api = await createSuperAxios(axios, {
  storage: { type: "redis", redisUri: "redis://127.0.0.1:6379" },
  defaultCacheOptions: {
    useCache: true,
    staleTime: 5 * 60 * 1000, // 5 minutes
  },
});

📘 Examples

1. GET request with cache

const response = await api.get("https://jsonplaceholder.typicode.com/todos/1", {
  cacheOptions: {
    useCache: true,
    staleTime: 10000, // 10 seconds
  },
});

console.log(response);

2. POST request with custom cache key

const response = await api.post(
  "https://jsonplaceholder.typicode.com/posts",
  {
    title: "foo",
    body: "bar",
    userId: 1,
  },
  {
    cacheOptions: {
      useCache: true,
      staleTime: 10000, // 10 seconds
      key: "custom-post-key", // cache key override
    },
  }
);

console.log(response);

3. DELETE request with caching

const response = await api.delete(
  "https://jsonplaceholder.typicode.com/posts/1",
  {
    cacheOptions: {
      useCache: true,
      staleTime: 10000,
    },
  }
);

console.log(response);

4. Permanent caching (never stale)

const response = await api.get("https://jsonplaceholder.typicode.com/todos/1", {
  cacheOptions: {
    useCache: true,
    staleTime: -1, // never expires
  },
});

console.log(response);

⚡ Cache Options

Each request supports a cacheOptions field:

| Option | Type | Default | Description | |-------------|---------|-----------|-------------| | useCache | boolean | false | Whether to use caching for this request | | staleTime | number | 300000 (5 min) | How long (in ms) the cached data is valid. Use -1 for never stale | | key | string | auto-generated (url+payload) | Custom cache key |

🔧 API

createSuperAxios(axiosInstance, options)

Parameters:

• axiosInstance: Your axios instance (or axios directly).
• options:
  • storage: { type: "redis", redisUri: string }
  • defaultCacheOptions: { useCache?: boolean; staleTime?: number }

Returns:

A super-axios instance with all axios methods (get, post, put, delete, etc.) + caching.

🔄 Revalidation (optional)

If you need to force refresh the cache manually:

await api.revalidate("custom-post-key");

🗑️ Cleanup (optional)

If you need to force clear the cache manually:

await api.clear();

✅ Summary

• Install with pnpm install @qbit-labs/super-axios
• Create a wrapper with createSuperAxios
• Use cacheOptions to control per-request caching
• Works the same as axios but faster with caching