@solumjs/cache

Caching with decorator-based cache management. InMemory and Redis cache stores.

Install

npm install @solumjs/cache

Cache Decorators

import { Cacheable, CacheEvict, CachePut, CacheManager } from "@solumjs/cache";
import { Bean } from "@solumjs/core";

@Bean("IProductService")
export class ProductService {

    @Cacheable("products", 300, "{id}")
    async findById(id: string): Promise<Product> {
        // Only executed if not in cache
        return this.productRepo.findById(id);
    }

    @CachePut("products", 300, "{id}")
    async update(id: string, dto: UpdateProductDto): Promise<Product> {
        // Always executes and updates cache
        return this.productRepo.update(id, dto);
    }

    @CacheEvict("products")
    async delete(id: string): Promise<void> {
        await this.productRepo.delete(id);
    }
}

Decorator Signatures

Cacheable(cacheName: string, ttlSeconds?: number, keyExpression?: string)
CachePut(cacheName: string, ttlSeconds?: number, keyExpression?: string)
CacheEvict(cacheName: string)

Cache Key Expression

// Named params resolved from method arguments
@Cacheable("users", 60, "{id}")
async findById(id: string) { /* ... */ }

// Positional syntax
@Cacheable("orders", 60, "{0}:item:{1}")
async getOrderItem(orderId: string, itemId: string) { /* ... */ }

CacheManager

import { cacheManager } from "@solumjs/cache";

// Get from cache
const value = await cacheManager.get("key");

// Set cache
await cacheManager.set("key", value, 60);

// Evict by prefix
await cacheManager.evict("users");

// Sweep expired entries
const removed = await cacheManager.sweep();

// Clear all
await cacheManager.clear();

InMemoryCacheStore

import { InMemoryCacheStore } from "@solumjs/cache";

// Default: 10000 entries
const store = new InMemoryCacheStore();

// Custom max entries
const store = new InMemoryCacheStore(5000);

RedisCacheStore

import { RedisCacheStore, connectRedis } from "@solumjs/cache";

const client = await connectRedis("redis://localhost:6379");
const store = new RedisCacheStore(client);

// Set as default store
cacheManager.useStore(store);

resolveCacheKey

import { resolveCacheKey } from "@solumjs/cache";

const key = resolveCacheKey("{id}", ["123"]);
// "123"

const key = resolveCacheKey("{0}:item:{1}", ["order-1", "item-2"]);
// "order-1:item-2"

Disposable Cache Entries (ES2026 using)

Auto-evicting cache entries using ES2026 Explicit Resource Management.

import { DisposableCacheEntry, AsyncDisposableCacheEntry, cacheManager } from "@solumjs/cache";

// Sync disposable - auto-evicts when leaving scope
{
    using entry = new DisposableCacheEntry(cacheManager, "temp:data", { foo: "bar" }, 300);
    console.log(entry.value); // { foo: "bar" }
    // automatically evicted when leaving this block
}

// Async disposable - for async contexts
async function handleRequest() {
    await using entry = new AsyncDisposableCacheEntry(cacheManager, "session:abc", sessionData, 600);
    // entry.value is sessionData
    // automatically evicted when leaving this async function
}

License

MIT