const cache = new Cache({ useClones: false, // Store references (no cloning) enableStats: false, // Disable statistics enableEvents: false, // Disable events stdTTL: 0, // Disable TTL checking checkPeriod: 0, // Disable expiration checks maxPerformance: true, // Use Map storage }) // Now faster than lru-cache! cache.set('key', value) // 30ns vs lru-cache 40ns cache.get('key') // 4ns vs lru-cache 12ns

import { createCache } from '@stacksjs/ts-cache' const cache = createCache() // Uses memory driver by default // Store a value (with 5 minute TTL) await cache.set('user:123', { name: 'John', role: 'admin' }, 300) // Retrieve a value with type safety const user = await cache.get<{ name: string, role: string }>('user:123') if (user) { console.log(user.name) // TypeScript knows this is a string } // Check if a key exists if (await cache.has('user:123')) { // Key exists and is not expired } // Delete a key await cache.del('user:123')

import { createCache } from '@stacksjs/ts-cache' const cache = createCache({ driver: 'redis', url: 'redis://localhost:6379', prefix: 'myapp', stdTTL: 3600, // Default TTL: 1 hour }) // Same API as memory cache await cache.set('session:abc', { userId: 1 }) const session = await cache.get('session:abc') // Close connection when done await cache.close()

const cache = createCache() // Create namespaced caches const userCache = cache.namespace('users') const postCache = cache.namespace('posts') await userCache.set('1', { name: 'Alice' }) await postCache.set('1', { title: 'Hello World' }) // No collision between namespaces console.log(await userCache.get('1')) // { name: 'Alice' } console.log(await postCache.get('1')) // { title: 'Hello World' }

// Set values with tags await cache.set('user:1', { name: 'John' }) await cache.tag('user:1', ['users', 'active']) await cache.set('user:2', { name: 'Jane' }) await cache.tag('user:2', ['users', 'premium']) // Get all keys by tag const userKeys = await cache.getKeysByTag('users') // Delete all entries with a tag await cache.deleteByTag('users')

// Fetch from cache or compute if missing const user = await cache.remember('user:1', 60, async () => { // Only called if cache miss return await database.getUser(1) }) // Remember forever (no expiration) const config = await cache.rememberForever('config', async () => { return await loadConfig() })

import { RateLimiter } from '@stacksjs/ts-cache' const limiter = new RateLimiter(cache, 100, 60) // 100 requests per 60 seconds const result = await limiter.check('user:123') if (result.limited) { console.log('Rate limited! Try again at:', new Date(result.resetAt)) } else { console.log('Request allowed. Remaining:', result.remaining) }

import { CacheLock } from '@stacksjs/ts-cache' const lock = new CacheLock(cache, 30) // 30 second lock timeout const result = await lock.withLock('critical:resource', async () => { // This code only runs if lock is acquired return await performCriticalOperation() }) if (result === null) { console.log('Could not acquire lock') }

import { memoize } from '@stacksjs/ts-cache' async function expensiveFunction(a: number, b: number) { // Expensive computation return a + b } const memoized = memoize(expensiveFunction, cache, { ttl: 60, keyGenerator: (a, b) => `sum:${a}:${b}`, }) // First call computes console.log(await memoized(5, 3)) // Computes and caches // Second call uses cache console.log(await memoized(5, 3)) // Returns cached result

import { CacheAside } from '@stacksjs/ts-cache' const pattern = new CacheAside(cache) // Load data on-demand const user = await pattern.get('user:123', async (key) => { return await database.getUser(123) }, 3600)

import { ReadThrough } from '@stacksjs/ts-cache' const pattern = new ReadThrough(cache, async (key) => { return await database.get(key) }, 3600) const data = await pattern.get('key')

import { WriteThrough } from '@stacksjs/ts-cache' const pattern = new WriteThrough(cache, async (key, value) => { await database.save(key, value) }) // Writes to both cache and database await pattern.set('user:123', userData, 3600)

import { WriteBack } from '@stacksjs/ts-cache' const pattern = new WriteBack( cache, async (key, value) => await database.save(key, value), 1000, // Flush delay in ms ) // Writes to cache immediately, database later await pattern.set('user:123', userData) // Manually flush pending writes await pattern.flush()

import { RefreshAhead } from '@stacksjs/ts-cache' const pattern = new RefreshAhead( cache, async key => await fetchFreshData(key), 3600, // TTL 0.8, // Refresh when 80% of TTL has passed ) // Returns cached value, refreshes in background if stale const data = await pattern.get('key')

import { createCache, MultiLevelPattern } from '@stacksjs/ts-cache' const l1 = createCache({ driver: 'memory', maxKeys: 100 }) const l2 = createCache({ driver: 'redis' }) const pattern = new MultiLevelPattern([l1, l2], [300, 3600]) // Checks L1, then L2, populates higher levels on hit const value = await pattern.get('key') // Writes to all levels await pattern.set('key', 'value')

// Set multiple values at once await cache.mset([ { key: 'key1', value: 'value1', ttl: 60 }, { key: 'key2', value: 'value2', ttl: 120 }, { key: 'key3', value: 'value3' }, ]) // Get multiple values at once const values = await cache.mget(['key1', 'key2', 'key3']) console.log(values) // { key1: 'value1', key2: 'value2', key3: 'value3' } // Delete multiple keys await cache.del(['key1', 'key2'])

import { createCache, serializers } from '@stacksjs/ts-cache' const cache = createCache({ driver: 'redis', serializer: serializers.auto, // Auto-detects and preserves types }) // Complex data types are preserved await cache.set('date', new Date()) await cache.set('regex', /test/gi) await cache.set('set', new Set([1, 2, 3])) await cache.set('map', new Map([['a', 1]])) // Available serializers: // - serializers.json (default) // - serializers.string // - serializers.number // - serializers.boolean // - serializers.buffer // - serializers.auto (preserves types) // - serializers.msgpack (requires msgpack-lite)

cache.on('hit', (key, value) => { console.log(`Cache hit: ${key}`) }) cache.on('miss', (key) => { console.log(`Cache miss: ${key}`) }) cache.on('set', (key, value, ttl) => { console.log(`Cache set: ${key}`) }) cache.on('del', (keys, count) => { console.log(`Deleted ${count} keys`) }) cache.on('flush', () => { console.log('Cache flushed') })

const stats = await cache.getStats() console.log(stats) // { // hits: 127, // misses: 9, // keys: 42, // ksize: 840, // vsize: 2390 // }

// cache.config.ts import type { CacheConfig } from '@stacksjs/ts-cache' const config: CacheConfig = { // General Settings driver: 'memory', // 'memory' | 'memory-lru' | 'redis' prefix: 'myapp', verbose: true, // Common Cache Settings stdTTL: 3600, // Default TTL in seconds checkPeriod: 600, // Cleanup interval maxKeys: 1000, useClones: true, // Redis Configuration redis: { url: process.env.REDIS_URL, host: 'localhost', port: 6379, password: process.env.REDIS_PASSWORD, database: 0, }, // Compression compression: { algorithm: 'gzip', // 'gzip' | 'brotli' | 'smart' | 'none' level: 6, threshold: 1024, // Only compress if larger than 1KB enabled: true, }, // Middleware middleware: { enabled: true, logging: true, metrics: true, retry: { enabled: true, maxRetries: 3, initialDelay: 100, }, }, // Caching Patterns patterns: { refreshAhead: { ttl: 3600, thresholdPercentage: 0.8, // Refresh when 80% of TTL passed }, slidingWindow: { ttl: 3600, // Reset TTL on access }, }, // Event Hooks events: { onSet: (key, value) => console.log(`Set: ${key}`), onGet: (key, value) => console.log(`Get: ${key}`), onMiss: key => console.log(`Miss: ${key}`), }, // Performance Tuning performance: { enableStats: true, batchSize: 100, warmup: { enabled: true, keys: ['popular:item:1', 'popular:item:2'], }, }, // Multi-Level Cache multiLevel: { enabled: true, levels: [ { driver: 'memory', ttl: 300, maxKeys: 1000 }, // L1: Fast { driver: 'redis', ttl: 3600 }, // L2: Persistent ], }, // TTL Strategy ttlStrategy: { mode: 'sliding', // 'fixed' | 'sliding' | 'probabilistic' jitter: 0.1, // Add 10% jitter to prevent thundering herd }, // Error Handling errorHandling: { throwOnError: false, circuitBreaker: { enabled: true, threshold: 5, timeout: 60000, }, }, // Debug Mode debug: { enabled: false, logLevel: 'info', trackAccess: true, }, } export default config

const cache = createCache({ driver: 'memory', stdTTL: 3600, // Default TTL in seconds checkPeriod: 600, // Check for expired items every 10 minutes maxKeys: 1000, // Maximum number of keys useClones: true, // Clone values on get/set deleteOnExpire: true, // Remove items when they expire prefix: 'myapp', // Key prefix for namespacing })

const cache = createCache({ driver: 'redis', url: 'redis://localhost:6379', // Redis connection URL // Or use individual options: host: 'localhost', port: 6379, password: 'secret', database: 0, // Connection options connectionTimeout: 5000, autoReconnect: true, maxRetries: 10, tls: false, // Cache options stdTTL: 3600, prefix: 'myapp', })

import { CircuitBreaker } from '@stacksjs/ts-cache' const breaker = new CircuitBreaker(cache, 5, 60) // 5 failures in 60 seconds try { const result = await breaker.execute('api:endpoint', async () => { return await callExternalAPI() }) } catch (error) { console.log('Circuit breaker is open') }

import { CacheWarmer } from '@stacksjs/ts-cache' const warmer = new CacheWarmer(cache) await warmer.warm([ { key: 'user:1', fetcher: () => getUser(1), ttl: 3600 }, { key: 'user:2', fetcher: () => getUser(2), ttl: 3600 }, ])

import { DebouncedCache } from '@stacksjs/ts-cache' const debounced = new DebouncedCache(cache, 1000) // 1 second delay // Multiple rapid calls only write once debounced.set('key', 'value1') debounced.set('key', 'value2') debounced.set('key', 'value3') // Only this value is written after 1 second

import { Cache, createCache } from '@stacksjs/ts-cache' // Old synchronous API (still works) const syncCache = new Cache() syncCache.set('key', 'value') const syncValue = syncCache.get('key') // New async API (recommended) const asyncCache = createCache() await asyncCache.set('key', 'value') const asyncValue = await asyncCache.get('key')