@b9g/cache-redis

Redis cache adapter for Shovel's universal cache system.

Features

- HTTP-aware caching: Stores complete HTTP responses with headers and status codes
- TTL support: Respects Cache-Control: max-age headers, with configurable default TTL
- Vary header support: Full HTTP content negotiation with Vary header checking
- Size limits: Configurable maximum entry size to prevent memory issues
- Connection pooling: Uses the official Redis client with connection management
- Error resilience: Graceful handling of Redis connection issues

Installation

``bash
bun install @b9g/cache-redis
`

Usage

$3

`typescript
import {CustomCacheStorage} from "@b9g/cache";
import {RedisCache} from "@b9g/cache-redis";

// Create cache storage with Redis backend
const cacheStorage = new CustomCacheStorage((name: string) =>
new RedisCache(name, {
redis: {
url: "redis://localhost:6379"
},
defaultTTL: 3600, // 1 hour
prefix: "myapp"
})
);

// Use the cache
const cache = await cacheStorage.open("pages");
await cache.put(request, response);
const cached = await cache.match(request);
`

$3

`typescript
import {RedisCache} from "@b9g/cache-redis";

// Create a single Redis cache instance
const cache = new RedisCache("my-cache", {
redis: {
url: process.env.REDIS_URL || "redis://localhost:6379",
password: process.env.REDIS_PASSWORD
},
defaultTTL: 3600,
maxEntrySize: 5 1024 1024 // 5MB max per entry
});

await cache.put(request, response);
const cached = await cache.match(request);
`

Configuration Options

$3

- redis?: RedisClientOptions - Redis connection configuration
- prefix?: string - Key prefix for Redis keys (default: "cache")
- defaultTTL?: number - Default TTL in seconds (0 = no expiration)
- maxEntrySize?: number - Maximum cache entry size in bytes (default: 10MB)

$3

The redis option accepts all standard Redis client options:

`typescript
{
redis: {
url: "redis://localhost:6379",
password: "your-password",
database: 0,
connectTimeout: 10000,
lazyConnect: true
}
}
`

Environment Variables

Common Redis configuration via environment variables:

- REDIS_URL - Complete Redis connection URL
- REDIS_HOST - Redis hostname
- REDIS_PORT - Redis port
- REDIS_PASSWORD - Redis password
- REDIS_DB - Redis database number

Performance Considerations

$3

Large responses are automatically rejected to prevent memory issues:

`typescript
const cache = new RedisCache("large-files", {
maxEntrySize: 1024 * 1024 // 1MB limit
});
`

$3

Configure TTL based on your caching strategy:

`typescript
// Short-lived API responses
const apiCache = new RedisCache("api", {
defaultTTL: 300 // 5 minutes
});

// Long-lived static assets
const staticCache = new RedisCache("static", {
defaultTTL: 86400 // 24 hours
});

// Permanent cache (manual invalidation)
const permanentCache = new RedisCache("permanent", {
defaultTTL: 0 // No expiration
});
`

$3

The Redis client automatically manages connection pooling. For high-traffic applications, consider tuning connection settings:

`typescript
{
redis: {
socket: {
connectTimeout: 10000,
keepAlive: true,
noDelay: true
},
isolationPoolOptions: {
min: 2,
max: 10
}
}
}
`

Error Handling

The Redis cache gracefully handles connection issues:

- Failed connections return undefined for cache misses
- Connection errors are logged but don't crash the application
- Automatic reconnection when Redis becomes available

Exports

$3

- RedisCache - Redis-backed cache implementation (extends Cache from @b9g/cache)

$3

- RedisCacheOptions` - Configuration options for RedisCache

Shovel Integration

This cache adapter is designed to work seamlessly with Shovel's cache-first architecture:

- Platform agnostic: Works with any Shovel platform (Bun, Node.js, Cloudflare)
- HTTP-aware: Preserves response headers and status codes
- ServiceWorker compatible: Implements the standard Cache API interface

For more information about Shovel's caching system, see the @b9g/cache documentation.