axcache

A powerful caching wrapper for Axios with advanced features including TTL (Time To Live), cache invalidation, and memory management.

Features

• 🚀 Automatic caching of GET requests
• ⏰ Configurable TTL (Time To Live) for cache entries
• 🧹 Automatic cache cleanup and memory management
• 💾 Size-based cache eviction (LRU)
• 🔄 Force refresh capability
• 🎯 Selective cache invalidation
• 📊 Cache statistics and monitoring
• ⚙️ Full Axios configuration support

Installation

npm install axcache

Basic Usage

import createAxcache from 'axcache';

// Create an instance with default options
const axcache = createAxcache();

// Make a GET request - it will be cached
const response = await axcache.get('https://api.example.com/data');

// Subsequent identical requests will use the cache
const cachedResponse = await axcache.get('https://api.example.com/data');

Troubleshooting

ESM/CommonJS Issues

If you're experiencing import issues:

1. For ESM projects:

import createAxcache from 'axcache';

2. For CommonJS projects:

const createAxcache = require('axcache');

Advanced Configuration

const axcache = createAxcache({
  // Axcache specific options
  stdTTL: 3600, // Cache TTL in seconds (default: 24 hours)
  maxSizeMB: 50, // Max cache size in MB (default: 50MB)
  onCacheHit: (key) => console.log(`Cache hit: ${key}`),
  onCacheMiss: (key) => console.log(`Cache miss: ${key}`),
  onCacheWrite: (key) => console.log(`Cache write: ${key}`),

  // Standard Axios options
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer token',
  },
  validateStatus: (status) => status < 500,
});

Configuration Options

Axcache Options

| Option | Type | Default | Description | | -------------- | ---------- | ----------- | ------------------------------- | | stdTTL | number | 86400 | Default TTL in seconds | | maxSizeMB | number | 50 | Maximum cache size in megabytes | | onCacheHit | function | undefined | Callback for cache hits | | onCacheMiss | function | undefined | Callback for cache misses | | onCacheWrite | function | undefined | Callback for cache writes |

Axios Options

All standard Axios configuration options are supported. Common options include:

| Option | Type | Default | Description | | ---------------- | ---------- | ----------- | ------------------------- | | baseURL | string | undefined | Base URL for requests | | timeout | number | undefined | Request timeout in ms | | headers | object | undefined | Request headers | | auth | object | undefined | Basic auth credentials | | responseType | string | undefined | Response type | | validateStatus | function | undefined | Define valid status codes |

API Methods

get(url[, config])

Makes a GET request with caching support.

// Basic GET request
const response = await axcache.get('https://api.example.com/data');

// With custom TTL
const response = await axcache.get('https://api.example.com/data', {
  ttl: 300, // 5 minutes
});

// Force refresh (bypass cache)
const response = await axcache.get('https://api.example.com/data', {
  forceRefresh: true,
});

invalidateCache(url[, params])

Invalidates cache for specific URL and parameters.

axcache.invalidateCache('https://api.example.com/data', { id: 1 });

getCacheStats()

Returns current cache statistics.

const stats = axcache.getCacheStats();
// {
//   entries: 10,
//   currentSize: 256000,
//   maxSizeMB: 50,
//   lastCleanup: 1648389120000
// }

Migration Example

Before (with Axios)

import axios from 'axios';

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

After (with axcache)

import createAxcache from 'axcache';

const api = createAxcache({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  stdTTL: 3600,
  maxSizeMB: 10, // 10MB cache size
});

Examples

Basic Caching

import createAxcache from 'axcache';

const api = createAxcache();

// This request will be cached
const users = await api.get('https://api.example.com/users');

// This request will use the cached response
const cachedUsers = await api.get('https://api.example.com/users');

Custom Cache Duration

const api = createAxcache({
  stdTTL: 3600, // Default 1 hour cache
});

// Override TTL for specific requests
const shortLivedData = await api.get('https://api.example.com/prices', {
  ttl: 300, // Cache for 5 minutes
});

const longLivedData = await api.get('https://api.example.com/constants', {
  ttl: 86400, // Cache for 24 hours
});

Force Refresh

const api = createAxcache();

// Initial request (cached)
const data = await api.get('https://api.example.com/data');

// Force a fresh request, ignoring cache
const freshData = await api.get('https://api.example.com/data', {
  forceRefresh: true,
});

Cache Monitoring

const api = createAxcache({
  maxSizeMB: 10,
  onCacheHit: (key) => console.log(`Cache hit: ${key}`),
  onCacheMiss: (key) => console.log(`Cache miss: ${key}`),
  onCacheWrite: (key) => console.log(`Cache write: ${key}`),
});

// Monitor cache statistics
setInterval(() => {
  const stats = api.getCacheStats();
  console.log('Cache stats:', {
    entries: stats.entries,
    size: `${(stats.currentSize / (1024 * 1024)).toFixed(2)}MB`,
    maxSize: `${stats.maxSizeMB}MB`,
  });
}, 60000);

With Authentication

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

// All requests will include the Authorization header
const protectedData = await api.get('/protected-endpoint');

Selective Cache Invalidation

const api = createAxcache();

// Cache some data
await api.get('/users/123');
await api.get('/users/123/posts');

// Invalidate specific cache entry
api.invalidateCache('/users/123');

// Invalidate with query parameters
api.invalidateCache('/users', { role: 'admin' });

Best Practices

1. Configure TTL Appropriately

   • Use shorter TTL for frequently changing data
   • Use longer TTL for static content
   • Consider using custom TTL per request when needed

2. Memory Management

   • Monitor cache size using getCacheStats()
   • Set appropriate maxSize based on your application's memory constraints
   • Consider your application's traffic patterns when setting cache size

3. Cache Invalidation

   • Use forceRefresh for one-time cache bypass
   • Use invalidateCache for programmatic cache clearing
   • Implement proper cache invalidation strategies based on your data update patterns

4. Axios Configuration

   • Set appropriate timeouts
   • Configure proper base URLs
   • Set up authentication headers when needed
   • Use proper error handling

Acknowledgments

This project uses the following major dependencies:

• Axios - Licensed under MIT

License

ISC © Salvatore Criniti

This project is licensed under the ISC License - see the LICENSE file for details. The dependencies included in this project are licensed under their own respective licenses.