nshilon-cache

a cache mechanism for nodejs services

• lightweight with small memory footprint,
• smart eviction strategy
• exponential backoff retry mechanism

Installation

npm install nshilon-cache

Usage

Here's how to use the cache service:

import { CacheService } from 'nshilon-cache';
import { MongoClient } from 'mongodb';
import { firstValueFrom } from 'rxjs';

// Initialize MongoDB connection and cache
const client = new MongoClient(process.env.MONGODB_URI);
const db = client.db(process.env.DB_NAME);
const userCollection = db.collection('users');

interface UserDocument {
    _id: string;
    name: string;
    email: string;
    // ... other fields
}

// Create cache instance
const userCache = new CacheService(userCollection);

export async function findUserById(id: string) {
    try {
        // Using the cache service with RxJS
        const user = await firstValueFrom(userCache.getById(id));
        return user;
    } catch (error) {
        console.error('Error finding user:', error);
        throw error;
    }
}

// Example of invalidating cache when updating user
export async function updateUser(id: string, updateData: Partial<UserDocument>) {
    try {
        const result = await userCollection.updateOne(
            { _id: new ObjectId(id) },
            { $set: updateData }
        );
        
        // Invalidate cache after update
        userCache.invalidate(id);
        
        return result;
    } catch (error) {
        console.error('Error updating user:', error);
        throw error;
    }
}

This implementation includes:

1. Cache Management:

   • Uses Map for in-memory storage
   • Maintains access patterns (count and timestamp)
   • Implements TTL-based expiration
   • Implements LRU (Least Recently Used) with access count consideration

2. Error Handling:

   • Implements exponential backoff retry mechanism
   • Configurable retry attempts and initial delay
   • Proper error propagation

3. Performance Optimizations:

   • Short-circuit returns for cache hits
   • Automatic cleanup of expired entries
   • Efficient eviction strategy for cache full scenarios

4. Features:

   • Configurable cache size and TTL
   • Cache statistics
   • Cache invalidation methods
   • Thread-safe operations

API Reference

Cache Service

class CacheService<T> {
    constructor(
        findById: (id: string) => Promise<T | null>,
        maxSize?: number,
        ttlMs?: number
    )

    getById(id: string): Observable<T | null>
    invalidate(id: string): void
    clear(): void
    getCacheStats(): { size: number, maxSize: number }
    invalidateAll(): void
}

• findById: A function that fetches data from the database.
• maxSize: Maximum number of items to store in the cache. Defaults to 1000.
• ttlMs: Time-to-live in milliseconds. Defaults to 5 minutes.

License

MIT