Cachly

A type-safe, production-ready in-memory cache system for Node.js and TypeScript, featuring advanced dependency tracking, intelligent invalidation, TTL, stale-while-revalidate, async operations, event system, statistics, advanced eviction, partitioning, compression, circuit breaker, distributed support, tags, groups, bulk operations, decorators, middleware, CLI tools, and cache hit/miss hooks.

Features

• Type-safe API with full TypeScript support
• Dependency tracking and automatic invalidation
• TTL and stale-while-revalidate
• Async loader integration (getOrCompute, getOrComputeWithStale)
• Event system for monitoring
• Statistics and monitoring
• Eviction policies: LRU, LFU, TTL
• Partitioning and namespace support
• Persistence adapters (Redis, File System)
• Compression (gzip, brotli, lz4)
• Circuit breaker pattern
• Distributed cache support
• Cache warming strategies
• Tags and bulk invalidation
• Cache groups for organization
• Bulk operations for performance
• Cache introspection and analytics
• Decorators for easy integration
• Express middleware for web apps
• CLI tool for management
• Cache hit/miss hooks for custom logic

Installation

1npm install cachly

Quick Start

1import { Cachly } from 'cachly';
2
3const cache = new Cachly({
4  maxItems: 1000,
5  defaultTtl: 60000,
6  staleWhileRevalidate: true,
7  compression: { enabled: true, algorithm: 'gzip', threshold: 1024 },
8});
9
10// Set and get
11await cache.set('user:1', { id: 1, name: 'John' });
12const user = await cache.get('user:1');
13
14// Async computation
15const stats = await cache.getOrCompute('stats', async () => computeExpensiveStats(), { ttl: 30000 });
16
17// Dependency tracking
18await cache.set('post:1', postData, { dependsOn: ['user:1'] });
19cache.delete('user:1'); // Also invalidates post:1

Cache Hit/Miss Hooks

You can run custom logic on every cache hit or miss, e.g. for logging, metrics, or tracing.

Via Config

1const cache = new Cachly({
2  onHit: (key) => {
3    console.log('Cache HIT:', key);
4  },
5  onMiss: (key) => {
6    console.log('Cache MISS:', key);
7  }
8});
9
10await cache.set('foo', 123);
11await cache.get('foo'); // logs: Cache HIT: foo
12await cache.get('bar'); // logs: Cache MISS: bar

Via Methods

1const cache = new Cachly();
2
3cache.setHitHook((key) => {
4  // Custom logic for hit
5  console.log('HIT', key);
6});
7
8cache.setMissHook((key) => {
9  // Custom logic for miss
10  console.log('MISS', key);
11});

Advanced Features

Tags and Bulk Operations

1// Set with tags
2await cache.set('user:1', userData, { tags: ['users', 'active'] });
3await cache.set('user:2', userData, { tags: ['users', 'inactive'] });
4
5// Invalidate by tag
6await cache.invalidateByTag('users'); // Removes all user data
7
8// Bulk operations
9const results = await cache.bulk({
10  get: ['key1', 'key2'],
11  set: [
12    { key: 'key3', value: 'value3' },
13    { key: 'key4', value: 'value4', options: { ttl: 5000 } }
14  ],
15  delete: ['old-key'],
16  invalidateByTag: ['expired-tag']
17});

Cache Groups

1// Create and manage groups
2const userGroup = cache.createGroup('users', { maxItems: 100 });
3cache.addToGroup('users', 'user:1');
4cache.addToGroup('users', 'user:2');
5
6// Get group keys
7const userKeys = cache.getGroupKeys('users');
8
9// Delete entire group
10cache.deleteGroup('users');

Cache Introspection

1// Pattern-based key discovery
2const userKeys = cache.getKeysByPattern('user:*');
3const postKeys = cache.getKeysByPattern('post:*');
4
5// Analytics
6const topKeys = cache.getTopKeys(10);
7const leastUsed = cache.getLeastUsedKeys(10);
8const oldestKeys = cache.getKeysByAge(10);

Decorators

1import { cache, cacheWithTags, invalidateTags } from 'cachly';
2
3class UserService {
4  @cache({ ttl: 30000 })
5  async getUser(id: string) {
6    return await fetchUserFromDB(id);
7  }
8
9  @cacheWithTags(['users'], 60000)
10  async getUsers() {
11    return await fetchUsersFromDB();
12  }
13
14  @invalidateTags(['users'])
15  async updateUser(id: string, data: any) {
16    return await updateUserInDB(id, data);
17  }
18}

Express Middleware

1import express from 'express';
2import { createCacheMiddleware, createInvalidateMiddleware } from 'cachly';
3
4const app = express();
5const cache = new Cachly();
6
7// Cache middleware
8app.use('/api/users', createCacheMiddleware({
9  cache,
10  ttl: 30000,
11  tags: (req) => ['users', req.params.id],
12  skip: (req) => req.method !== 'GET'
13}));
14
15// Invalidate middleware
16app.post('/api/users/:id', createInvalidateMiddleware({
17  cache,
18  tags: ['users']
19}));

CLI Tool

1# Install globally
2npm install -g cachly
3
4# Start CLI
5cachly
6
7# Available commands
8cachly> help
9cachly> set user:1 "John Doe" 30000
10cachly> get user:1
11cachly> stats
12cachly> keys user:*
13cachly> top 10
14cachly> clear

API Reference

Basic Operations

1await cache.set<T>(key: string, value: T, options?: CacheOptions): Promise<void>
2await cache.get<T>(key: string): Promise<T | undefined>
3cache.has(key: string): boolean
4cache.delete(key: string): void
5cache.clear(): void

Async Operations

1await cache.getOrCompute<T>(key: string, loader: () => Promise<T>, options?: CacheOptions): Promise<T>
2await cache.getOrComputeWithStale<T>(key: string, loader: () => Promise<T>, options?: CacheOptions): Promise<T>

Tags & Groups

1await cache.invalidateByTag(tag: string): Promise<string[]>
2await cache.invalidateByTags(tags: string[]): Promise<Record<string, string[]>>
3cache.getKeysByTag(tag: string): string[]
4cache.getTagsByKey(key: string): string[]
5cache.createGroup(name: string, config?: Partial<CacheConfig>): CacheGroup
6cache.addToGroup(groupName: string, key: string): boolean
7cache.getGroupKeys(groupName: string): string[]
8cache.deleteGroup(groupName: string): boolean

Bulk Operations

1await cache.bulk(operation: BulkOperation): Promise<any>

Cache Introspection

1cache.getKeys(pattern?: string): string[]
2cache.getKeysByPattern(pattern: string): string[]
3cache.getTopKeys(limit?: number): Array<{ key: string; accessCount: number }>
4cache.getLeastUsedKeys(limit?: number): Array<{ key: string; accessCount: number }>
5cache.getKeysByAge(limit?: number): Array<{ key: string; age: number }>

Events

1cache.on('hit', (key) => { /* ... */ });
2cache.on('miss', (key) => { /* ... */ });
3cache.on('set', (key, value) => { /* ... */ });
4cache.on('delete', (key) => { /* ... */ });
5cache.on('evict', (key, reason) => { /* ... */ });
6cache.on('compress', (key, originalSize, compressedSize) => { /* ... */ });
7cache.on('partitionHit', (partition, key) => { /* ... */ });
8cache.on('tagInvalidated', (tag, affectedKeys) => { /* ... */ });
9cache.on('bulkOperation', (operation, result) => { /* ... */ });
10cache.on('groupCreated', (group) => { /* ... */ });
11cache.on('groupDeleted', (groupName) => { /* ... */ });

Statistics & Monitoring

1const stats = cache.stats();
2// { hits, misses, evictions, memoryUsage, keyCount, totalAccesses, hitRate, missRate, avgLoadTime, compressionRatio }
3
4const metrics = cache.metrics();
5// { hitRate, missRate, avgLoadTime, memoryEfficiency, compressionRatio, circuitBreakerTrips, partitionDistribution }
6
7const health = cache.health();
8// { status, issues, lastCheck, uptime }

Advanced Features

• Partitioning: getPartitionInfo(partitionId), getAllPartitions(), isBalanced()
• Circuit Breaker: getCircuitBreakerState()
• Cache Warming: warm(items), warmProgressive(items), warmWithDependencies(items)

Configuration

1interface CacheConfig {
2  maxItems?: number;
3  maxMemory?: number;
4  defaultTtl?: number;
5  staleWhileRevalidate?: boolean;
6  log?: boolean;
7  namespace?: string;
8  persistence?: 'none' | PersistenceAdapter;
9  evictionPolicy?: 'lru' | 'ttl' | 'manual' | 'lfu';
10  compression?: { enabled: boolean; algorithm: 'gzip' | 'brotli' | 'lz4'; threshold: number; };
11  circuitBreaker?: { enabled: boolean; failureThreshold: number; recoveryTimeout: number; };
12  partitioning?: { enabled: boolean; strategy: 'hash' | 'range' | 'custom'; partitions: number; };
13  monitoring?: { enabled: boolean; metrics: string[]; };
14  distributed?: { enabled: boolean; nodes: string[]; replication: boolean; consistency: 'eventual' | 'strong'; partitionStrategy: string; };
15  onHit?: (key: string) => void;
16  onMiss?: (key: string) => void;
17}

Persistence Adapters

1import { FSAdapter } from 'cachly';
2const cache = new Cachly({ persistence: new FSAdapter('./cache') });

Namespaces & Partitioning

1import { CachlyNamespace } from 'cachly';
2const userCache = CachlyNamespace.namespace('user');
3const postCache = CachlyNamespace.namespace('post');

Cache Warming

1await cache.warm([
2  { key: 'config', loader: loadConfig, ttl: 120000 },
3  { key: 'meta', loader: fetchMeta },
4  { key: 'stats', loader: computeStats, dependsOn: ['config'] }
5]);

License

MIT