Performance

SoulCache is designed for performance. Here are optimization strategies.

Bundle Size

SoulCache has zero runtime dependencies and a small bundle:

// Import only what you need
import { QueryClient } from '@soulcache/core';
import { useQuery } from '@soulcache/react';

Tree Shaking

SoulCache supports tree shaking. Import only what you need:

// Good: Import specific exports
import { QueryClient, CacheEngine } from '@soulcache/core';
import { useQuery } from '@soulcache/react';
 
// All packages declare sideEffects: false

Caching Strategies

TTL Caching

Configure the cache eviction lifetime. Background refetching and retry are internal modules targeted for future milestones.

const client = new QueryClient({
  defaultOptions: {
    gcTime: 30 * 60 * 1000, // 30 minutes
  },
});

Memory Management

Garbage Collection

// Manual garbage collection
client.getCache().collectGarbage();
 
// Automatic with gcTime
const client = new QueryClient({
  defaultOptions: {
    gcTime: 5 * 60 * 1000, // 5 minutes (override)
  },
});

Observer Cleanup

// Always unsubscribe
const unsubscribe = client.subscribe(['users'], callback);
 
// Cleanup when done
unsubscribe();

Network Optimization

Deduplication

// Automatic deduplication
const p1 = client.fetchQuery({ queryKey: ['users'], queryFn });
const p2 = client.fetchQuery({ queryKey: ['users'], queryFn });
 
// Only one network request
const [data1, data2] = await Promise.all([p1, p2]);

Request Coalescing

// Requests are coalesced automatically
for (let i = 0; i < 10; i++) {
  client.fetchQuery({ queryKey: ['users'], queryFn });
}
// Only one network request

Monitoring

// Get cache statistics
const stats = client.getCache().getStats();
console.log('Cache size:', stats.size);
console.log('Active entries:', stats.activeEntries);
 
// Get query metrics
const metrics = client.getScheduler().getMetrics();
console.log('Tasks completed:', metrics.totalCompleted);

Best Practices

Set appropriate stale time — Balance freshness vs performance
Use garbage collection — Prevent memory leaks
Monitor metrics — Detect performance issues
Optimize queries — Use selective queries
Clean up subscriptions — Prevent memory leaks

Performance

On this page