ltcache

A lightweight, in-memory caching library - like Redis but much simpler. Features TTL support, concurrent request handling, and comprehensive statistics. Perfect for Node.js applications and frontend applications that need fast caching without the complexity of Redis.

✨ Features

• 🚀 Lightweight: Zero external dependencies, minimal memory footprint
• ⏱️ TTL Support: Automatic expiration with configurable time-to-live
• 🔄 Concurrent Safe: Multiple simultaneous requests for the same key only call the function once
• 📊 Statistics: Built-in hit rate tracking and cache size monitoring
• 🎯 Pattern Removal: Remove multiple keys using regex patterns
• 🔒 TypeScript: Full type safety with generics
• ⚡ Fast: In-memory storage for maximum performance
• 🌐 Universal: Works in Node.js, browsers, React, Vue, and other frontend frameworks

📦 Installation

npm install ltcache

🚀 Quick Start

import {cache} from 'ltcache';

// Create a cache instance
const cacheInstance = cache();

// Create a cache instance with debug logging enabled
const debugCache = cache(true);

// Simple caching
cacheInstance.set('user:123', {name: 'Alice', email: '[email protected]'}, 3600); // 1 hour TTL
const user = await cacheInstance.get('user:123');

// Caching with fallback function
const user = await cacheInstance.get('user:123', async () => {
  // This function only runs if the key doesn't exist
  return await fetchUserFromDatabase(123);
}, 3600); // Cache for 1 hour

// Get cache statistics
const stats = cacheInstance.report();
console.log(`Hit rate: ${stats.hitRate}%`);

📚 Documentation

• API Reference - Complete API documentation
• Examples - Common usage patterns and examples

🎯 Use Cases

Perfect for:

• API Response Caching: Cache expensive API calls
• Database Query Results: Store frequently accessed data
• Configuration Storage: Cache app configuration
• Session Data: Store temporary user session information
• Microservices: Lightweight caching between services
• Frontend Apps: Cache API responses, user preferences, and computed data in React, Vue, and other frameworks
• Browser Storage: Lightweight alternative to localStorage with TTL support
• SPA Performance: Improve app responsiveness by caching expensive operations

When to use ltcache vs Redis:

Use ltcache when:

• You need simple, fast caching
• You want zero external dependencies
• Your cache fits in memory
• You don't need persistence across restarts
• You want minimal setup and configuration
• You're building frontend applications (React, Vue, etc.) and need client-side caching

Use Redis when:

• You need persistence across application restarts
• You need to share cache across multiple applications (though ltcache could be used as the foundation for a Redis-style server)
• You need advanced data structures (lists, sets, etc.)
• You need pub/sub functionality
• You need clustering or replication

🔧 Advanced Usage

Debug Mode

Enable debug logging to see cache operations in real-time:

// Create cache with debug logging enabled
const cache = cache(true);

// All cache operations will now log to console
await cache.get('user:123', async () => {
  return await fetchUserFromDatabase(123);
});
// Output: miss: user:123
// Output: set: user:123

await cache.get('user:123');
// Output: hit: user:123

Concurrent Request Handling

// Multiple simultaneous requests for the same key
const promises = [
  cache.get('expensive-data', async () => {
    await new Promise(resolve => setTimeout(resolve, 1000));
    return 'result';
  }),
  cache.get('expensive-data', async () => {
    await new Promise(resolve => setTimeout(resolve, 1000));
    return 'result';
  }),
  cache.get('expensive-data', async () => {
    await new Promise(resolve => setTimeout(resolve, 1000));
    return 'result';
  })
];

const results = await Promise.all(promises);
// All three promises resolve to the same value
// The expensive function is only called once

Pattern-based Removal

// Cache some data
cache.set('user:123:profile', profileData);
cache.set('user:123:settings', settingsData);
cache.set('user:456:profile', profileData2);
cache.set('config:app', appConfig);

// Remove all user data for user 123
cache.remove(/^user:123:/);

// Remove all user profiles
cache.remove(/^user:.*:profile$/);

// Remove all config
cache.remove(/^config:/);

Cache Statistics

const stats = cache.report();
console.log({
  items: stats.numItems,        // Number of cached items
  hitRate: stats.hitRate,       // Hit rate percentage
  sizeKb: stats.sizeKb          // Estimated memory usage
});

🧪 Testing

npm test

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📈 Performance

ltcache is designed for speed and efficiency:

• Memory efficient: Uses Map for O(1) lookups
• Concurrent safe: Handles multiple simultaneous requests efficiently
• Minimal overhead: Zero external dependencies
• Fast expiration: Efficient timeout management

🔗 Related Projects

• Redis - Full-featured in-memory data store
• node-cache - Another Node.js caching library
• lru-cache - LRU cache implementation

Made with ❤️ by Marc H. Weiner