@veltany/next-object-cache

A powerful, multi-layered persistent object cache for Next.js and React applications. Optimize performance by cascading data across multiple storage layers (In-memory, Redis, LibSQL/KV) with automated hydration and thundering herd protection.

Features

• Multi-Layer Architecture: Chain multiple adapters (L1 In-memory, L2 Redis, L3 Database) in a priority sequence.
• Automated Hydration: When a lower-level cache hits (e.g., Redis), it automatically "back-fills" the faster upper layers (e.g., In-memory).
• Thundering Herd Protection: Prevents multiple simultaneous requests for the same expired key from hitting your database at once.
• Tag-based Invalidation: Group cache entries by tags and clear them all at once.
• Graceful Degradation: If one adapter fails (e.g., Redis goes down), the service automatically falls back to the next available layer.

Installation

npm install @veltany/next-object-cache

Quick Start## Basic Usage

import { objectCache } from '@veltany/next-object-cache';

// Set a value with a 5-minute TTL and tags await cache.set('user:123', { name: 'John Doe' }, { ttl: 300000, tags: ['users'] }); // Get a value const user = await cache.get('user:123');

3. The Power Move: getOrFetch

Use this to wrap your database queries. It handles checking the cache, fetching the data if it's missing, and saving it back—all while preventing duplicate fetches.

const data = await cache.getOrFetch('dashboard_stats', async () => { return await db.orders.getStats(); }, { ttl: 60000, tags: ['orders'] });

API Reference## get(key: string)

Cascades through adapters. If a hit occurs in a lower level, it hydrates higher levels automatically.

set(key, value, options)

Sets the value across all registered adapters.

• options.ttl: Time to live in milliseconds.
• options.tags: String array for grouped invalidation.
• options.skipLevels: Array of levels (numbers) to bypass.

invalidateByTag(tag: string)

Clears all entries across all adapters associated with the specific tag.

delete(key: string)

Removes a specific key from all cache layers.

Configuration

The service responds to the following environment variables (or your internal config):

• ENABLE_CACHE: Toggle the entire service on/off.
• GLOBAL_CACHE_KEY: Prefix for all keys (default: app).
• DEBUG_MODE: Enables verbose logging of hits/misses.

License

MIT © veltany