@cachehub/upstash-redis-cache

Upstash Redis cache implementation for CacheHub with hybrid string and TypeCacheKey support.

Installation

pnpm add @cachehub/upstash-redis-cache @upstash/redis

Usage

To use the Upstash Redis cache adapter in your application, follow these steps:

1. Import the Upstash Redis cache package to register it with the factory. For example:

   import '@cachehub/upstash-redis-cache';

2. Create a cache instance using the factory.
3. Use the cache instance to set, get, delete, and check cache entries.

import '@cachehub/upstash-redis-cache';
import { UpstashRedisCacheFactory } from '@cachehub/upstash-redis-cache';

const factory = new UpstashRedisCacheFactory();
const cache = await factory.createCache({
  CACHE_TYPE: 'upstash-redis-cache',
  REDIS_URL: process.env.REDIS_URL!,
  REDIS_TOKEN: process.env.REDIS_TOKEN!,
});

// Set and get primitive types
await cache.set<string>('stringKey', 'value');
const stringValue = await cache.get<string>('stringKey');

await cache.set<number>('numberKey', 42);
const numberValue = await cache.get<number>('numberKey');

await cache.set<boolean>('booleanKey', true);
const booleanValue = await cache.get<boolean>('booleanKey');

// Set and get complex objects
interface User {
  id: number;
  name: string;
  email: string;
}

const user: User = {
  id: 1,
  name: 'John Doe',
  email: '[email protected]'
};

await cache.set<User>('userKey', user);
const userValue = await cache.get<User>('userKey');

// Set and get arrays
await cache.set<string[]>('arrayKey', ['a', 'b', 'c']);
const arrayValue = await cache.get<string[]>('arrayKey');

// Basic cache operations
await cache.delete('key');
const exists = await cache.has('key');

TypeCacheKey Support

The adapter supports structured cache keys for advanced scenarios:

import type { TypeCacheKey } from '@cachehub/core';

// Using structured cache keys
const licenseKey: TypeCacheKey = {
  namespace: 'license',
  id: 'ABC-123',
  context: {
    action: 'activation',
    domain: 'example.com',
    ipAddress: '192.168.1.1'
  }
};

// Store with structured key
await cache.set(licenseKey, { token: 'xyz789', expires: Date.now() + 3600000 });

// Retrieve with structured key
const licenseData = await cache.get(licenseKey);

// Pattern deletion - delete all cache entries for license ABC-123
await cache.delete({
  namespace: 'license',
  id: 'ABC-123'
  // Omitting context deletes ALL entries matching namespace and id
});

// Delete all license entries
await cache.delete({
  namespace: 'license'
  // Omitting id deletes ALL entries in the namespace
});

Pattern Deletion Support

The UpstashRedisCache provides native pattern deletion using Redis SCAN operations:

✅ All Deletion Patterns Supported:

// Exact key deletion with TypeCacheKey
await cache.delete({ 
  namespace: 'license', 
  id: 'ABC-123',
  context: { action: 'activation', domain: 'example.com' }
});

// Namespace + ID deletion (deletes all contexts for that ID)
await cache.delete({ 
  namespace: 'license', 
  id: 'ABC-123' 
});

// Partial context deletion (deletes all entries matching partial context)
await cache.delete({ 
  namespace: 'license', 
  context: { action: 'activation' }  // Deletes all activations regardless of ID
});

// Namespace-only deletion (deletes all entries in namespace)
await cache.delete({ 
  namespace: 'license' 
});

// String key deletion
await cache.delete('exact-string-key');

How It Works:

• Redis SCAN: Uses native Redis SCAN operations with MATCH patterns
• Immediate Consistency: Deletions complete immediately using DEL command
• Efficient Batching: Processes keys in batches of 100 for optimal performance
• Native Redis Operations: Leverages Redis cluster-safe operations

Key Serialization

TypeCacheKey objects are automatically serialized to deterministic strings:

• { namespace: 'license', id: '123' } → 'license|123'
• { namespace: 'license', id: '123', context: { action: 'activation' } } → 'license|123|action:activation'
• Context keys are sorted alphabetically for consistency

Configuration

The Upstash Redis cache requires the following configuration:

interface TypeUpstashRedisCacheConfig {
  /**
   * The Redis URL
   */
  REDIS_URL: string;

  /**
   * The Redis token
   */
  REDIS_TOKEN: string;

  /**
   * Optional prefix for cache keys
   */
  keyPrefix?: string;
}

Testing

To run the tests, create a .env file with your Upstash Redis credentials:

REDIS_URL=your_redis_url
REDIS_TOKEN=your_redis_token

Then run:

pnpm test