@happyvertical/cache

Unified caching interface supporting Memory, File, Redis, and S3 backends with TTL, eviction policies, batch operations, and compression. All providers implement the same CacheProvider interface, so you can swap backends without changing application code.

Installation

pnpm add @happyvertical/cache
# Requires @happyvertical/utils as a peer
# redis and @aws-sdk/client-s3 are bundled

Quick Start

import { getCache } from '@happyvertical/cache';

const cache = await getCache({
  provider: 'memory',
  maxSize: 100 * 1024 * 1024,
  evictionPolicy: 'lru',
});

await cache.set('user:123', { name: 'Alice' }, 3600); // TTL in seconds
const user = await cache.get('user:123');
await cache.delete('user:123');
await cache.close();

Providers

Memory

In-process Map-based cache. No external dependencies. Data lost on restart.

const cache = await getCache({
  provider: 'memory',
  namespace: 'app',
  defaultTTL: 3600,          // seconds
  maxSize: 100 * 1024 * 1024, // bytes (default 100MB)
  maxEntries: 10000,          // default 10k
  evictionPolicy: 'lru',      // 'lru' | 'lfu' | 'fifo'
  checkPeriod: 60000,          // expiration sweep interval in ms
});

File

Stores entries as files on disk with optional gzip compression. Persists across restarts.

const cache = await getCache({
  provider: 'file',
  cacheDir: './cache',         // required
  compression: true,           // gzip (default false)
  maxSize: 500 * 1024 * 1024,  // bytes (default 500MB)
  fileExtension: '.cache',
  checkPeriod: 300000,         // cleanup interval in ms
});

Redis

Distributed cache using the redis npm client. Supports optional gzip compression for large values.

const cache = await getCache({
  provider: 'redis',
  host: 'localhost',
  port: 6379,
  password: 'secret',
  db: 0,
  namespace: 'app',
  enableCompression: true,
  compressionThreshold: 1024, // bytes — only compress values larger than this
  connectTimeout: 5000,       // ms
});

S3

Stores entries as S3 objects. Useful for CI caches that must persist between runs. Compression enabled by default to reduce egress costs.

const cache = await getCache({
  provider: 's3',
  bucket: 'my-cache-bucket',
  prefix: 'cache/',
  region: 'us-east-1',
  compression: true,           // default true
  compressionThreshold: 1024,  // bytes
});

API

All providers implement CacheProvider:

interface CacheProvider {
  get<T>(key: string): Promise<T | undefined>;
  set<T>(key: string, value: T, ttl?: number): Promise<void>;
  has(key: string): Promise<boolean>;
  delete(key: string): Promise<boolean>;
  clear(namespace?: string): Promise<void>;
  keys(pattern?: string): Promise<string[]>;
  getMany<T>(keys: string[]): Promise<Map<string, T>>;
  setMany<T>(entries: Array<{ key: string; value: T; ttl?: number }>): Promise<void>;
  deleteMany(keys: string[]): Promise<number>;
  touch(key: string, ttl: number): Promise<boolean>;
  getStats(): Promise<CacheStats>;
  close(): Promise<void>;
}

• TTL is always in seconds. Omit for no expiration.
• keys() accepts glob patterns (user:*, report:2024*).
• touch() updates TTL without modifying the value. Returns false if the key doesn't exist.
• Batch ops (getMany, setMany, deleteMany) reduce round-trips, especially for Redis.

Environment Variables

Configuration can be loaded from HAVE_CACHE_* environment variables via @happyvertical/utils/loadEnvConfig. Programmatic options always take precedence.

Variable	Maps to	Notes
HAVE_CACHE_PROVIDER	provider	memory, file, redis, s3
HAVE_CACHE_NAMESPACE	namespace
HAVE_CACHE_DEFAULT_TTL	defaultTTL	seconds
HAVE_CACHE_MAX_SIZE	maxSize	bytes (memory/file)
HAVE_CACHE_MAX_ENTRIES	maxEntries	memory only
HAVE_CACHE_EVICTION_POLICY	evictionPolicy	memory only
HAVE_CACHE_CACHE_DIR	cacheDir	file only
HAVE_CACHE_COMPRESSION	compression	file/s3
HAVE_CACHE_HOST	host	redis only
HAVE_CACHE_PORT	port	redis only
HAVE_CACHE_PASSWORD	password	redis only
HAVE_CACHE_BUCKET	bucket	s3 only
HAVE_CACHE_PREFIX	prefix	s3 only
HAVE_CACHE_REGION	region	s3 only

Error Classes

All errors extend CacheError(message, code, provider):

• CacheKeyError — invalid key (empty or >250 chars)
• CacheConnectionError — backend unreachable (Redis)
• CacheSizeError — entry would exceed maxSize
• CacheSerializationError — JSON serialize/deserialize failure

Exported Utilities

Low-level helpers re-exported from shared/utils:

• isValidKey(key) — check key length constraints
• calculateSize(value) — approximate JSON byte size
• matchesPattern(pattern, str) — glob matching
• formatKey(namespace, key) / extractKey(namespace, fullKey) — namespace prefixing
• isExpired(expiresAt) / calculateExpiration(ttl) — TTL math
• serialize(value) / deserialize(json) — JSON wrappers