Smart Tiered Cache

A Redis-compatible caching system with intelligent multi-tier storage that automatically moves data between RAM, SSD (RocksDB), and SQLite based on access patterns.

Features

• Redis Protocol Compatible - Use with any Redis client (redis-cli, ioredis, node-redis, etc.)
• Three-Tier Storage - RAM → SSD (RocksDB) → SQLite with automatic data movement
• Intelligent Tiering - Hot data stays in RAM, warm data in SSD, cold data in SQLite
• Configurable Thresholds - Customize hot/warm/cold access frequency thresholds
• Multiple Eviction Policies - LRU, LFU, or hybrid eviction strategies
• TTL Support - Key expiration with lazy and background cleanup
• Data Structures - Lists, Hashes, and Sets support
• Persistence - Automatic snapshots and recovery on restart
• Monitoring Dashboard - HTTP API + WebSocket for real-time metrics
• Zero External Dependencies - All storage is embedded (no Redis/database server needed)

Installation

npm install smart-tiered-cache

Quick Start

As a Standalone Server

# Start the cache server
npx smart-tiered-cache

# Or with custom config
CACHE_REDIS_PORT=6380 CACHE_RAM_TIER_MAX_BYTES=2147483648 npx smart-tiered-cache

Then connect with any Redis client:

redis-cli -p 6379
> SET mykey "hello"
OK
> GET mykey
"hello"

As a Library

import { start, shutdown } from 'smart-tiered-cache';

// Start the cache
const app = await start({
  configOverrides: {
    redisPort: 6379,
    dashboardPort: 8080,
    ramTierMaxBytes: 1024 * 1024 * 1024, // 1GB RAM
    ssdTierMaxBytes: 10 * 1024 * 1024 * 1024, // 10GB SSD
    hotThreshold: 10,    // 10+ accesses/min → RAM
    warmThreshold: 1,    // 1-10 accesses/min → SSD
    coldThreshold: 0.1,  // <0.1 accesses/min → SQLite
  }
});

// Use the cache engine directly
await app.cacheEngine.set('key', Buffer.from('value'));
const result = await app.cacheEngine.get('key');
console.log(result?.data.toString()); // "value"
console.log(result?.tier); // "ram"

// Graceful shutdown
await shutdown(app);

Programmatic Usage (Without Server)

import { CacheEngine, RAMTier, SSDTier, DBTier, AccessTracker, TierManager, EvictionPolicy } from 'smart-tiered-cache';

// Initialize storage tiers
const ramTier = new RAMTier();
await ramTier.open({ capacityBytes: 1024 * 1024 * 1024 }); // 1GB

const ssdTier = new SSDTier();
await ssdTier.open({ capacityBytes: 10 * 1024 * 1024 * 1024, storagePath: './data/ssd' });

const dbTier = new DBTier();
await dbTier.open({ capacityBytes: Number.MAX_SAFE_INTEGER, storagePath: './data/cache.db' });

// Initialize components
const accessTracker = new AccessTracker();
const evictionPolicy = new EvictionPolicy('lru');
const tierManager = new TierManager({
  hotAccessFrequency: 10,
  warmAccessFrequency: 1,
  coldAccessFrequency: 0.1,
});

// Create cache engine
const cache = new CacheEngine(
  { ramTier, ssdTier, dbTier, accessTracker, tierManager, evictionPolicy },
  { trackAccess: true }
);

await cache.start();

// Use the cache
await cache.set('user:123', Buffer.from(JSON.stringify({ name: 'John' })));
const user = await cache.get('user:123');

await cache.shutdown();

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CACHE_REDIS_PORT | 6379 | Redis protocol port | | CACHE_DASHBOARD_PORT | 8080 | Dashboard HTTP port | | CACHE_MAX_CONNECTIONS | 1000 | Max concurrent connections | | CACHE_RAM_TIER_MAX_BYTES | 1073741824 (1GB) | RAM tier capacity | | CACHE_SSD_TIER_MAX_BYTES | 10737418240 (10GB) | SSD tier capacity | | CACHE_HOT_THRESHOLD | 10 | Accesses/min for hot (RAM) | | CACHE_WARM_THRESHOLD | 1 | Accesses/min for warm (SSD) | | CACHE_COLD_THRESHOLD | 0.1 | Accesses/min for cold (DB) | | CACHE_EVICTION_POLICY | lru | lru, lfu, or hybrid | | CACHE_TIER_MOVEMENT_INTERVAL_MS | 5000 | Tier evaluation interval |

Config File (config.json)

{
  "redisPort": 6379,
  "dashboardPort": 8080,
  "ramTierMaxBytes": 1073741824,
  "ssdTierMaxBytes": 10737418240,
  "hotThreshold": 10,
  "warmThreshold": 1,
  "coldThreshold": 0.1,
  "evictionPolicy": "lru",
  "tierMovementIntervalMs": 5000
}

Supported Redis Commands

String Operations

• GET key - Get value
• SET key value [EX seconds] [NX|XX] - Set value with optional TTL
• DEL key [key ...] - Delete keys
• EXISTS key [key ...] - Check if keys exist
• MGET key [key ...] - Get multiple values
• MSET key value [key value ...] - Set multiple values
• INCR key / DECR key - Atomic increment/decrement
• EXPIRE key seconds - Set TTL
• TTL key - Get remaining TTL

List Operations

• LPUSH key value [value ...] - Push to head
• RPUSH key value [value ...] - Push to tail
• LPOP key - Pop from head
• RPOP key - Pop from tail
• LRANGE key start stop - Get range

Hash Operations

• HSET key field value - Set field
• HGET key field - Get field
• HMSET key field value [field value ...] - Set multiple fields
• HMGET key field [field ...] - Get multiple fields
• HGETALL key - Get all fields

Set Operations

• SADD key member [member ...] - Add members
• SREM key member [member ...] - Remove members
• SMEMBERS key - Get all members
• SISMEMBER key member - Check membership

Dashboard API

Endpoints

| Endpoint | Description | |----------|-------------| | GET /metrics | Cache metrics (hit rate, ops/sec, tier usage) | | GET /keys/hot?n=10 | Top N hottest keys | | GET /tiers | Tier distribution statistics | | GET /health | Health check | | GET /suggestions | Optimization suggestions | | GET /cost | Cost/savings metrics | | GET /history?limit=60 | Historical utilization |

WebSocket

Connect to ws://localhost:8080 for real-time metrics updates.

How Tiering Works

1. New keys start in RAM (fastest tier)
2. Background processor runs every 5 seconds evaluating access patterns
3. Keys are promoted/demoted based on access frequency:
   • Hot (≥10 accesses/min) → RAM
   • Warm (≥1 access/min) → SSD (RocksDB)
   • Cold (<0.1 accesses/min) → SQLite
4. On shutdown, RAM data is persisted to SSD + snapshot
5. On startup, data is restored from snapshot + SSD/DB scan

Storage Technologies

| Tier | Technology | Use Case | |------|------------|----------| | RAM | JavaScript Map | Hot data, sub-millisecond access | | SSD | RocksDB (classic-level) | Warm data, fast persistent storage | | DB | SQLite (better-sqlite3) | Cold data, reliable long-term storage |

License

MIT

smart-tiered-cache