Caching

Configure an application-owned cache store, then use its Keyv manager for explicit reads, writes and eviction.

import 'reflect-metadata';
import {CACHE_STORE, Inject, injectable, type CacheStore} from '@heronjs/common';
 
@injectable()
export class CatalogProvider {
  constructor(@Inject(CACHE_STORE) private readonly store: CacheStore) {}
 
  async list(): Promise<string[]> {
    const cache = this.store.get();
    if (!cache) throw new Error('Cache is not initialized');
    const cached: unknown = await cache.get('catalog');
    if (Array.isArray(cached) && cached.every((value): value is string => typeof value === 'string')) {
      return cached;
    }
    const items = ['example'];
    await cache.set('catalog', items, 60000);
    return items;
  }
 
  async refresh() {
    await this.store.get()?.delete('catalog');
  }
}

Register the provider in your module and declare a default store. Keyv TTLs are milliseconds. Validate values read from a cache before using them. Include user identity or other inputs in keys when cached results depend on them.

Decorator metadata

@Cacheable and @Evict remain exported from @heronjs/common, but the 4.0.0 Fastify route adapter does not apply their metadata to REST responses. Use explicit cache operations for HTTP handlers instead of assuming the 3.7.11 response-caching example still works.

The application’s cache event handler supports exact-key eviction, * for clearing the store, and wildcard patterns when the backend supports iteration. The application owns cache connections and disconnects them during await app.close().