axios-cache-interceptor-keyv

Universal storage adapter using Keyv for axios-cache-interceptor - supports Redis, SQLite, MongoDB, PostgreSQL and more backends.

Features

• Universal Storage: One adapter, multiple backends (Redis, SQLite, MongoDB, PostgreSQL, etc.)
• High Performance: Built on Keyv's optimized storage layer
• TypeScript First: Full TypeScript support with strict typing
• TTL Management: Automatic expiration handling
• Error Resilient: Graceful fallbacks for storage failures
• Zero Dependencies: Only peer dependencies for maximum compatibility

Installation

npm install axios-cache-interceptor-keyv @keyvhq/core axios-cache-interceptor

yarn add axios-cache-interceptor-keyv @keyvhq/core axios-cache-interceptor

pnpm add axios-cache-interceptor-keyv @keyvhq/core axios-cache-interceptor

bun add axios-cache-interceptor-keyv @keyvhq/core axios-cache-interceptor

Note: This package works with both the original keyv and the newer @keyvhq/core libraries. We recommend using @keyvhq/core for new projects as it's the actively maintained fork.

Quick Start

In-Memory Storage (Default)

import axios from 'axios';
import Keyv from '@keyvhq/core';
import {setupCache} from 'axios-cache-interceptor';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

const keyv = new Keyv(); // In-memory storage
const api = setupCache(axios, {
    storage: createKeyvStorage(keyv)
});

Redis Storage

import axios from 'axios';
import Keyv from '@keyvhq/core';
import {setupCache} from 'axios-cache-interceptor';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

const keyv = new Keyv('redis://localhost:6379');
const api = setupCache(axios, {
    storage: createKeyvStorage(keyv)
});

SQLite Storage

import axios from 'axios';
import Keyv from '@keyvhq/core';
import {setupCache} from 'axios-cache-interceptor';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

const keyv = new Keyv('sqlite://cache.db');
const api = setupCache(axios, {
    storage: createKeyvStorage(keyv)
});

MongoDB Storage

import axios from 'axios';
import Keyv from '@keyvhq/core';
import {setupCache} from 'axios-cache-interceptor';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

const keyv = new Keyv('mongodb://localhost:27017/cache');
const api = setupCache(axios, {
    storage: createKeyvStorage(keyv)
});

API

createKeyvStorage(keyv, options?)

Creates a storage adapter compatible with axios-cache-interceptor.

Parameters

• keyv (Keyv): A Keyv instance configured with your preferred backend
• options? (KeyvStorageOptions): Optional configuration object
  • debug? (boolean): Enable debug logging for cache operations (default: false)

Returns

• AxiosStorage: Storage adapter compatible with axios-cache-interceptor

Example

import Keyv from '@keyvhq/core';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

// In-memory storage
const storage = createKeyvStorage(new Keyv());

// Redis storage
const storage = createKeyvStorage(new Keyv('redis://localhost:6379'));

// With debug logging enabled
const debugStorage = createKeyvStorage(new Keyv(), { debug: true });

Supported Backends

This adapter works with any Keyv-compatible backend:

Official @keyvhq Core Adapters

| Backend | Connection String Example | Package Required | |----------------|---------------------------------------|---------------------| | Redis | redis://localhost:6379 | @keyvhq/redis | | MongoDB | mongodb://localhost:27017/db | @keyvhq/mongo | | SQLite | sqlite://cache.db | @keyvhq/sqlite | | PostgreSQL | postgresql://user:pass@localhost/db | @keyvhq/postgres | | MySQL | mysql://user:pass@localhost/db | @keyvhq/mysql | | File | file://path/to/cache | @keyvhq/file | | In-Memory | new Keyv() | None (built-in) |

Community Adapters

Additional storage adapters are available from the community. For a complete list, visit the Keyv Community Adapters page.

Popular community adapters include:

• keyv-anyredis - Redis clusters and alternative Redis clients
• keyv-dynamodb - DynamoDB storage adapter
• keyv-firestore - Firebase Cloud Firestore adapter
• keyv-lru - In-memory LRU back-end
• keyv-memcache - Memcache storage adapter
• keyv-mssql - Microsoft SQL Server adapter
• keyv-s3 - Amazon S3 storage adapter
• quick-lru - Simple "Least Recently Used" (LRU) cache

Advanced Usage

Custom TTL and Configuration

import Keyv from '@keyvhq/core';
import {setupCache} from 'axios-cache-interceptor';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

const keyv = new Keyv('redis://localhost:6379', {
    ttl: 1000 * 60 * 60, // 1 hour default TTL
    namespace: 'myapp'
});

const api = setupCache(axios, {
    storage: createKeyvStorage(keyv),
    ttl: 1000 * 60 * 15 // 15 minutes cache TTL
});

Error Handling

import Keyv from '@keyvhq/core';
import {setupCache} from 'axios-cache-interceptor';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

const keyv = new Keyv('redis://localhost:6379');

keyv.on('error', (error) => {
    console.error('Keyv connection error:', error);
});

const api = setupCache(axios, {
    storage: createKeyvStorage(keyv)
});

Multiple Cache Instances

import axios from 'axios';
import Keyv from '@keyvhq/core';
import {setupCache} from 'axios-cache-interceptor';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

// User data cache
const userCache = setupCache(axios.create(), {
    storage: createKeyvStorage(
        new Keyv('redis://localhost:6379', {namespace: 'users'})
    )
});

// Product data cache  
const productCache = setupCache(axios.create(), {
    storage: createKeyvStorage(
        new Keyv('redis://localhost:6379', {namespace: 'products'})
    )
});

Debug Logging

Enable debug logging to monitor cache operations:

import axios from 'axios';
import Keyv from '@keyvhq/core';
import {setupCache} from 'axios-cache-interceptor';
import {createKeyvStorage} from 'axios-cache-interceptor-keyv';

const keyv = new Keyv('redis://localhost:6379');
const api = setupCache(axios, {
    storage: createKeyvStorage(keyv, { debug: true })
});

// This will log cache operations like:
// [axios-cache-interceptor-keyv] SET: { key: 'get:https://api.example.com/users', state: 'cached', ttl: 300000 }
// [axios-cache-interceptor-keyv] FIND: { key: 'get:https://api.example.com/users', found: true }

Development

Prerequisites

• Bun runtime
• Node.js 18+ (for compatibility testing)

Setup

git clone https://github.com/angelxmoreno/axios-cache-interceptor-keyv.git
cd axios-cache-interceptor-keyv
bun install

Scripts

# Run tests
bun test

# Run tests with coverage
bun run test:coverage

# Lint code
bun run lint

# Fix linting issues
bun run lint:fix

# Type checking
bun run typecheck

# Build for production
bun run build

Testing

The test suite includes comprehensive tests for:

• Core functionality with in-memory Keyv
• TTL handling and expiration
• Error scenarios and edge cases
• Integration with different backends
• TypeScript type checking

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (bun test)
6. Run linting (bun run lint)
7. Commit your changes (git commit -m 'feat: add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Commit Convention

This project follows Conventional Commits:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• refactor: Code refactoring
• test: Test additions or modifications
• chore: Maintenance tasks

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• axios-cache-interceptor - HTTP request cache for axios
• @keyvhq/core - Simple key-value storage with support for multiple backends

Support

• Documentation
• Issues
• Discussions
• Discord

Made with ❤️ by Angel S. Moreno