# OpenSpec Change: enterprise-cache - **Change ID**: enterprise-cache - **Package**: `@suaveplan/cache` - **Category**: universal - **Target path**: `universal/database/cache` - **Status**: PROPOSED - **Date**: 2026-04-24 - **Reference spec**: `/mnt/s/web/suaveplan/enterprise/cache.md` --- ## Summary Deliver `@suaveplan/cache` on the genesis branch from scratch at enterprise quality. The package provides a type-safe caching abstraction: an `AbstractCache` base class, a built-in LRU `MemoryCache`, a `CacheFactory` with module-augmentation-based provider registry, namespaced caches, TTL support, stale-while-revalidate, multi-get/set, lifecycle hooks via `@suaveplan/events`, and cache statistics. Genesis adds structured errors via `@suaveplan/error`, Zod schemas for all option types, OTel instrumentation, injectable clock and RNG (no `Date.now()` at module scope), `AbortSignal` on async operations, property-based tests (fast-check), and a mitata benchmark suite. --- ## Current-state audit (genesis) The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data. --- ## Available workspace deps on genesis | Package | Role | |---|---| | `@suaveplan/error` (`workspace:^`) | Base class for `CacheError`; `defineCodes` for `CACHE.*` codes | | `@suaveplan/types` (`workspace:^`) | `Clock` (injectable for TTL expiry, `Date.now` replacement), `EventBusLike`, `LoggerLike` | | `@suaveplan/events` (`workspace:^`) | `EventBus` for lifecycle hooks (hit, miss, set, evict, expire) | | `zod` (`catalog:forms`) | Zod schemas for all public option types | | `@opentelemetry/api` (`catalog:observability`) | Spans + counters on every public cache operation | | `tslib` (`catalog:build`) | Runtime helpers | Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`), `@suaveplan/testing` (`workspace:^`). --- ## Preserved public API surface (from main branch) ### Abstract ```ts abstract class AbstractCache { abstract get(key: string): Promise abstract set(key: string, value: T, options?: CacheSetOptions): Promise abstract delete(key: string): Promise abstract clear(): Promise abstract has(key: string): Promise abstract getStats(): CacheStats abstract getMultiple(keys: string[]): Promise> abstract setMultiple(entries: CacheMultiSetEntry[]): Promise wrap(key: string, fn: () => Promise, options?: CacheWrapOptions): Promise } class NamespacedCache extends AbstractCache ``` ### Memory cache ```ts class MemoryCache extends AbstractCache { constructor(options?: CacheOptions) get(key: string): Promise set(key: string, value: T, options?: CacheSetOptions): Promise delete(key: string): Promise clear(): Promise has(key: string): Promise getStats(): CacheStats getMultiple(keys: string[]): Promise> setMultiple(entries: CacheMultiSetEntry[]): Promise } ``` ### Factory ```ts class CacheFactory { static create(type: CacheProviderType, config?: CacheProviderConfig): AbstractCache static register(type: string, impl: CacheProviderImplementation): void static unregister(type: string): void static has(type: string): boolean static providers(): string[] } function createCache(type: CacheProviderType, config?: CacheProviderConfig): AbstractCache function createCacheWithConfig(config: CacheFactoryConfig): AbstractCache function registerCacheProvider(type: string, impl: CacheProviderImplementation): void function unregisterCacheProvider(type: string): void function hasCacheProvider(type: string): boolean function getCacheProviders(): string[] function clearCacheProviders(): void ``` ### Types ```ts interface CacheEntry { value: T expiresAt: number createdAt: number lastAccessedAt: number hitCount: number } interface CacheStats { hits: number; misses: number; size: number; hitRate: number; memoryUsage?: number } type CacheEvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'ttl' interface CacheOptions { maxSize?: number defaultTTL?: number evictionPolicy?: CacheEvictionPolicy enableStats?: boolean checkExpirationInterval?: number } interface CacheSetOptions { ttl?: number; staleWhileRevalidate?: boolean; staleThreshold?: number } interface CacheWrapOptions { ttl?: number staleWhileRevalidate?: boolean staleThreshold?: number forceRefresh?: boolean shouldCache?: (value: T) => boolean } interface CacheTransformHook { name: string; transform: (key: string, value: T) => Promise | T; priority?: number } interface CacheMultiGetResult { found: Map; missing: string[] } interface CacheMultiSetEntry { key: string; value: T; options?: CacheSetOptions } type CacheProviderType = keyof CacheProviderRegistry interface CacheProviderConfig extends CacheOptions { [key: string]: unknown } type CacheProviderConfigFor = CacheProviderRegistry[K] extends new (opts: infer O) => unknown ? O : CacheProviderConfig interface CacheProviderImplementation { new(options?: CacheProviderConfig): AbstractCache } interface CacheFactoryConfig { type: CacheProviderType; options?: CacheProviderConfig } interface CacheProviderRegistry { memory: typeof MemoryCache } interface CacheEvents { hit: { key: string } miss: { key: string } set: { key: string; ttl?: number } delete: { key: string } clear: {} evict: { key: string; reason: 'ttl' | 'lru' | 'lfu' | 'manual' } expire: { key: string } } ``` ### Error codes ```ts type CacheErrorCode = | 'CACHE_KEY_INVALID' | 'CACHE_CAPACITY_EXCEEDED' | 'CACHE_PROVIDER_NOT_FOUND' | 'CACHE_SET_FAILED' | 'CACHE_GET_FAILED' | 'CACHE_SERIALIZATION_FAILED' ``` --- ## New additions for genesis ### 1. Structured `CacheError` `CacheError` extends `SuaveplanError` from `@suaveplan/error` carrying a `CacheErrorCode` discriminant. All internal throw sites use named factory helpers. ### 2. Zod option schemas - `CacheOptionsSchema` - `CacheSetOptionsSchema` - `CacheWrapOptionsSchema` - `CacheFactoryConfigSchema` - `CacheTransformHookSchema` ### 3. Injectable clock `CacheOptions` gains an optional `clock?: Clock` field (from `@suaveplan/types`). `MemoryCache` uses `clock.now()` for all TTL calculations instead of bare `Date.now()`. Defaults to `{ now: () => Date.now() }`. ### 4. Event bus integration `CacheOptions` gains an optional `events?: EventBusLike` field. When provided, `MemoryCache` emits typed `CacheEvents` on every hit/miss/set/delete/evict/expire. Uses `@suaveplan/events` `EventBus` shape — no external event emitter library. ### 5. AbortSignal on `wrap` `CacheWrapOptions` gains an optional `signal?: AbortSignal`. The background refresh in stale-while-revalidate is aborted when the signal fires. ### 6. OTel instrumentation | Operation | Signal | |---|---| | `get` | counter `cache.get_total`, attribute `cache.hit` (bool), attribute `cache.namespace` | | `set` | counter `cache.set_total`, attribute `cache.ttl_set` (bool) | | `delete` | counter `cache.delete_total` | | `clear` | counter `cache.clear_total` | | `wrap` | span `cache.wrap`, histogram `cache.wrap_duration_ms` | | `getStats` | gauge `cache.size`, gauge `cache.hit_rate` | ### 7. LFU eviction policy The `lfu` eviction policy is fully implemented (main branch had the type but the implementation may have been a stub). `MemoryCache` uses a frequency map + linked-list for O(1) LFU eviction when `evictionPolicy: 'lfu'` is set. ### 8. Property-based tests (fast-check) - **LRU eviction invariant**: after filling a cache of capacity N and setting N+1 items, assert the least-recently-used item is no longer present. - **TTL expiry**: for items set with TTL T, after advancing the injectable clock by T+1 ms, assert `has()` returns false and `get()` returns `undefined`. - **`getMultiple` completeness**: for M items set in cache and K random keys queried (K ≥ M), assert `found.size + missing.length === K` always. - **Stats accuracy**: for N random get/set/miss sequences, assert `hits + misses === total get calls` and `hitRate ≈ hits / (hits + misses)`. ### 9. Benchmark suite - `get_hot_1k`: 1000 `get()` calls, all hits, LRU cache of 500 items. - `set_1k`: 1000 `set()` calls with TTL. - `wrap_cold`: 100 `wrap()` calls where all miss (async factory call each time). - `lru_eviction_pressure`: fill cache to 2x capacity, measure eviction throughput. --- ## File layout ```text universal/database/cache/ package.json tsconfig.json vitest.config.ts src/ index.ts # Public barrel error-codes.ts # CACHE.* codes + registerCacheErrorCodes constants/ index.ts # DEFAULT_MAX_SIZE, DEFAULT_TTL, DEFAULT_EVICTION_POLICY types/ common.ts # All public TS interfaces and type aliases common.md schemas.ts # Zod schemas schemas.md abstract/ abstract-cache/ abstract-cache.ts # AbstractCache base class abstract-cache.md abstract-cache.types.ts abstract-cache.test.ts index.ts namespaced-cache/ namespaced-cache.ts namespaced-cache.md namespaced-cache.test.ts index.ts memory/ memory-cache/ memory-cache.ts # LRU/LFU/FIFO/TTL MemoryCache memory-cache.md memory-cache.types.ts memory-cache.test.ts index.ts factory/ cache-factory/ cache-factory.ts # CacheFactory class + free functions cache-factory.md cache-factory.types.ts cache-factory.test.ts index.ts registry/ registry.ts # Built-in memory provider registration registry.md index.ts __benchmarks__/ cache.bench.ts tests/ integration.test.ts # Cross-cutting: namespaced + factory + wrap round-trip property.test.ts # fast-check property tests ``` --- ## Impact **Downstream packages**: `@suaveplan/idempotency` and any server-side package that needs caching will depend on `@suaveplan/cache`. No existing genesis package currently requires it. **Breaking changes from main-branch API**: none. New optional fields (`clock`, `events`, `signal`) are additive. **Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events` must be published to Verdaccio before this package can be built or tested.