@fourjs/cache

A high-performance, feature-rich caching module with support for multiple providers, background refresh, and comprehensive monitoring.

Features

🚀 High Performance

Optimized hot-key caching
Automatic compression
Request deduplication
Batch operations

🔄 Multiple Cache Providers

In-memory caching
Redis integration
Browser localStorage
Custom provider support

📊 Advanced Features

Background refresh
Tag-based invalidation
TTL management
Event system
Real-time monitoring

⚛️ React Integration

React hooks and components
Automatic cache invalidation
Development tools
Performance monitoring

Installation

npm install @fourjs/cache

# Optional dependencies
npm install redis # For Redis support

Quick Start

Basic Usage

import { createCache } from '@fourjs/cache';

// Create cache instance
const cache = createCache({
  defaultTtl: 3600,
  backgroundRefresh: true
});

// Basic operations
await cache.set('user:123', { name: 'John' });
const user = await cache.get('user:123');

// Compute with caching
const result = await cache.getOrCompute(
  'expensive:calculation',
  async () => await performExpensiveCalculation()
);

React Integration

import { CacheProvider, useCache } from '@fourjs/cache';

function UserProfile({ userId }) {
  const { data, isLoading, error } = useCache(
    `user:${userId}`,
    async () => await fetchUserProfile(userId),
    { ttl: 3600 }
  );

  if (isLoading) return <Loading />;
  if (error) return <Error error={error} />;

  return <Profile data={data} />;
}

// Wrap your app with provider
function App() {
  return (
    <CacheProvider>
      <UserProfile userId="123" />
    </CacheProvider>
  );
}

Multiple Providers

import { createCache, MemoryAdapter, RedisAdapter } from '@fourjs/cache';

const cache = createCache({
  providers: [
    {
      name: 'memory',
      instance: new MemoryAdapter({ maxSize: '100mb' }),
      priority: 1
    },
    {
      name: 'redis',
      instance: new RedisAdapter({
        host: 'localhost',
        port: 6379
      }),
      priority: 2
    }
  ]
});

Background Refresh

const cache = createCache({
  backgroundRefresh: true,
  refreshThreshold: 0.75 // Refresh when 75% of TTL elapsed
});

// Value will be refreshed in background when stale
const value = await cache.getOrCompute(
  'key',
  async () => await fetchData(),
  { ttl: 3600 }
);

Tag-Based Invalidation

// Set values with tags
await cache.set('user:123', userData, {
  tags: ['user', 'profile']
});

await cache.set('user:123:posts', posts, {
  tags: ['user', 'posts']
});

// Invalidate by tag
await cache.invalidateByTag('posts');

Batch Operations

// Get multiple values
const results = await cache.getMany([
  'user:123',
  'user:123:posts',
  'user:123:settings'
]);

// Set multiple values
await cache.setMany({
  'user:123': userData,
  'user:123:posts': posts
}, { ttl: 3600 });

Monitoring

import { CacheMonitor } from '@fourjs/cache';

function Dashboard() {
  return (
    <CacheMonitor 
      refreshInterval={5000}
      showDetails={true}
    />
  );
}

Event System

import { subscribeToCacheEvents, CacheEventType } from '@fourjs/cache';

// Subscribe to events
const unsubscribe = subscribeToCacheEvents(
  CacheEventType.GET_HIT,
  (payload) => {
    console.log('Cache hit:', payload);
  }
);

// Cleanup
unsubscribe();

Custom Provider

import { ICacheProvider } from '@fourjs/cache';

class CustomProvider implements ICacheProvider {
  async get(key: string): Promise<any> {
    // Implementation
  }

  async set(key: string, value: any, options?: CacheOptions): Promise<void> {
    // Implementation
  }

  // ... other methods
}

Advanced Features

Compression

await cache.set('large:data', data, {
  compression: true,
  compressionThreshold: 1024 // Compress if > 1KB
});

Custom Serialization

const serializer = createSerializer({
  typeHandlers: {
    BigInt: {
      serialize: (v) => v.toString(),
      deserialize: (v) => BigInt(v)
    }
  }
});

await cache.set('key', value, { serializer });

Development Tools

import { CacheDebugPanel } from '@fourjs/cache';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && (
        <CacheDebugPanel position="bottom-right" />
      )}
    </>
  );
}

API Reference

See API Documentation for complete reference.

Configuration

interface CacheConfig {
  defaultTtl?: number;
  defaultOptions?: CacheOptions;
  deduplicateRequests?: boolean;
  backgroundRefresh?: boolean;
  refreshThreshold?: number;
  throwOnErrors?: boolean;
  logging?: boolean;
  logStackTraces?: boolean;
  logger?: (logEntry: any) => void;
}

Performance

Hot keys are cached in memory for fastest access
Automatic compression for large values
Request deduplication prevents redundant computations
Batch operations for efficient bulk processing
Background refresh prevents cache stampedes

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License - see LICENSE for details.

Package detail

@missionfabric/firstjs-cache

readme