# Tasks: enterprise-cache **Change ID**: enterprise-cache **Package**: `@suaveplan/cache` **Target path**: `universal/database/cache` **Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events` --- ## 1. Scaffold - [x] Create directory `universal/database/cache/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`. - [x] Write `package.json` at version `0.1.0` with: - `"type": "module"`, `"sideEffects": false` - `exports` map: top-level `"."` barrel plus subpaths `./abstract/abstract-cache`, `./abstract/namespaced-cache`, `./memory/memory-cache`, `./factory/cache-factory`, `./types/common`, `./types/schemas` - `dependencies`: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/events workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build` - `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `fast-check catalog:testing`, `mitata catalog:testing`, `@suaveplan/testing workspace:^` - [x] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`. - [x] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config` (pool: `forks`). - [x] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`, `bench` scripts to `package.json`. --- ## 2. Types + errors ### 2a. Common types (`src/types/common.ts` + `src/types/common.md`) - [x] Define all public TS interfaces: `CacheEntry`, `CacheStats`, `CacheEvictionPolicy`, `CacheOptions`, `CacheSetOptions`, `CacheWrapOptions`, `CacheTransformHook`, `CacheMultiGetResult`, `CacheMultiSetEntry`, `CacheProviderType`, `CacheProviderConfig`, `CacheProviderConfigFor`, `CacheProviderImplementation`, `CacheFactoryConfig`, `CacheProviderRegistry`, `CacheEvents`. - [x] Add genesis-only optional fields to `CacheOptions`: `clock?: Clock` (from `@suaveplan/types`), `events?: EventBusLike` (from `@suaveplan/types`). - [x] Add genesis-only optional field to `CacheWrapOptions`: `signal?: AbortSignal`. - [x] Write `src/types/common.md` (≥200 words, both simple + advanced examples, API reference for every type). ### 2b. Error codes (`src/error-codes.ts`) - [x] Import `CodeMetadata`, `ErrorCodes`, `SuaveplanError` from `@suaveplan/error`. - [x] Define `CacheErrorCode` union — six codes: `CACHE_KEY_INVALID`, `CACHE_CAPACITY_EXCEEDED`, `CACHE_PROVIDER_NOT_FOUND`, `CACHE_SET_FAILED`, `CACHE_GET_FAILED`, `CACHE_SERIALIZATION_FAILED`. - [x] Define `CACHE_ERROR_METADATA` with `httpStatus`, `severity`, `retryable`, `userMessageKey`, `category`, `description` for each code. - [x] Export `registerCacheErrorCodes()` — calls `ErrorCodes.registerMany(CACHE_ERROR_METADATA)`. Idempotent. - [x] Call `registerCacheErrorCodes()` as an eager side-effect at module scope. - [x] Export `CacheError` extending `SuaveplanError` carrying `CacheErrorCode` discriminant. ### 2c. Zod schemas (`src/types/schemas.ts` + `src/types/schemas.md`) - [x] Write `CacheOptionsSchema`, `CacheSetOptionsSchema`, `CacheWrapOptionsSchema`, `CacheFactoryConfigSchema`, `CacheTransformHookSchema`. - [x] Export inferred TypeScript types as companions where they differ from hand-written types. - [x] Write `src/types/schemas.md` (≥200 words). --- ## 3. Constants (`src/constants/index.ts`) - [x] Export `DEFAULT_MAX_SIZE = 1000`, `DEFAULT_TTL_SECONDS = 3600`, `DEFAULT_EVICTION_POLICY: CacheEvictionPolicy = 'lru'`, `DEFAULT_EXPIRATION_INTERVAL_MS = 60_000`. --- ## 4. Abstract base (`src/abstract/abstract-cache/`) - [x] Implement `AbstractCache` abstract class: - Abstract methods: `get`, `set`, `delete`, `clear`, `has`, `getStats`, `getMultiple`, `setMultiple`. - Concrete `wrap(key, fn, options?)`: - Check cache; if hit and not stale, return cached value. - If stale-while-revalidate: return stale value, trigger background refresh (respects `options.signal`). - If miss or expired: call `fn()`, store result if `shouldCache(value)` returns true. - OTel: span `cache.wrap`, histogram `cache.wrap_duration_ms`. - All methods protected by try/catch; on internal error throw `CacheError` with appropriate code. - [x] Write `abstract-cache.test.ts` — test `wrap` logic via a concrete in-memory subclass stub (no vi.mock). - [x] Write `abstract-cache.md` (≥200 words). ### 4b. NamespacedCache (`src/abstract/namespaced-cache/`) - [x] Implement `NamespacedCache` wrapping an `AbstractCache`: - Prefixes all keys with `"${namespace}:"`. - Delegates all methods to the wrapped cache. - `getStats()` returns stats scoped to the namespace where possible. - [x] Write `namespaced-cache.test.ts`: key isolation between namespaces, clear only clears own namespace. - [x] Write `namespaced-cache.md` (≥200 words). --- ## 5. Memory cache (`src/memory/memory-cache/`) - [x] Implement `MemoryCache` extending `AbstractCache`: - Internal store: `Map>`. - Injectable `clock?: Clock` — default `{ now: () => Date.now() }`. - Injectable `events?: EventBusLike` — emit `CacheEvents` on every operation. - LRU eviction: doubly-linked list + map for O(1) evict-on-capacity. - LFU eviction: frequency map + bucket list for O(1) evict-on-capacity. - FIFO eviction: insertion-order queue. - TTL eviction: periodic sweep via `setInterval` using injectable clock. - `setInterval` is cleared on `clear()` and optionally on explicit `dispose()`. - `getStats()` returns live counters (no `Date.now()` — use `clock.now()`). - Stale-while-revalidate: tracked in `CacheEntry` metadata. - OTel: counter `cache.get_total` (hit/miss), `cache.set_total`, `cache.delete_total`, `cache.clear_total`, gauge `cache.size`, gauge `cache.hit_rate`, counter `cache.evict_total` (with `reason` attribute). - [x] Write `memory-cache.test.ts` (≤500 lines): get/set/delete/clear/has, TTL expiry (advance injectable clock), LRU eviction, LFU eviction, stats accuracy, multi-get/set, namespace isolation, event emission. - [x] Write `memory-cache.md` (≥200 words, both basic + advanced example with injectable clock). --- ## 6. Factory (`src/factory/cache-factory/`) - [x] Implement `CacheFactory` class with static methods: `create`, `register`, `unregister`, `has`, `providers`. - [x] Implement free functions: `createCache`, `createCacheWithConfig`, `registerCacheProvider`, `unregisterCacheProvider`, `hasCacheProvider`, `getCacheProviders`, `clearCacheProviders`. - [x] `CacheFactory.create` validates the type against the registry; throws `CacheError(CACHE_PROVIDER_NOT_FOUND)` for unknown types. - [x] Write `cache-factory.test.ts`: register/unregister, create known + unknown type, `clearCacheProviders` resets state. - [x] Write `cache-factory.md` (≥200 words). ### Registry (`src/factory/registry/`) - [x] `registry.ts` — auto-registers `MemoryCache` as the `memory` provider on import (side-effect). - [x] Write `registry.md` explaining the auto-registration side-effect and tree-shaking implications. --- ## 7. Public barrel (`src/index.ts`) - [x] Re-export: `AbstractCache`, `NamespacedCache`, `MemoryCache`, `CacheFactory`, all free factory functions, all types, error-codes, constants. - [x] Import `./factory/registry` to trigger built-in provider registration on package load. --- ## 8. Property-based tests (`tests/property.test.ts`) Use `fast-check`. All timeouts: `{ timeout: 30000 }`. - [x] **LRU eviction invariant**: fill cache of capacity N (N in 5–20), set N+1 items with sequential access order; assert LRU item is evicted. - [x] **TTL expiry**: set items with TTL T (T in 1–100 ms), advance injectable clock by T+1; assert `has()` returns false. - [x] **`getMultiple` completeness**: for M items set and K keys queried, assert `found.size + missing.length === K`. - [x] **Stats accuracy**: for N random get/set sequences, assert `stats.hits + stats.misses === total get calls`. --- ## 9. Benchmarks (`src/__benchmarks__/cache.bench.ts`) Use `mitata`. - [x] `get_hot_1k`: 1000 `get()` on LRU cache of 500 pre-populated items (all hits). - [x] `set_1k`: 1000 `set()` with TTL = 60s. - [x] `wrap_cold_100`: 100 `wrap()` all misses, factory returns `Promise.resolve(1)`. - [x] `lru_eviction_pressure`: fill 2x capacity, measure throughput of evictions. - [x] Add `bench` script to `package.json`. - [x] Add placeholder benchmark table to `README.md`. --- ## 10. Docs - [x] `src/types/common.md` - [x] `src/types/schemas.md` - [x] `src/abstract/abstract-cache/abstract-cache.md` - [x] `src/abstract/namespaced-cache/namespaced-cache.md` - [x] `src/memory/memory-cache/memory-cache.md` - [x] `src/factory/cache-factory/cache-factory.md` - [x] `src/factory/registry/registry.md` - [x] Root `universal/database/cache/README.md` — purpose, installation, quick-start, dep table, full API symbol list, benchmarks table. --- ## 11. Verify and publish - [x] Run `bunx turbo lint --filter=@suaveplan/cache` — zero errors. - [x] Run `bunx turbo typecheck --filter=@suaveplan/cache` — zero errors. - [x] Run `bunx turbo test --filter=@suaveplan/cache` — all tests pass. - [x] Run `bunx turbo test:coverage --filter=@suaveplan/cache` — 100% on all touched modules. - [x] Run `bun run docs:check --filter=@suaveplan/cache` — zero errors. - [x] Confirm no `TODO`, `FIXME`, `@deprecated`, untyped `any`, `ts-ignore`, or `.skip` in `src/` or `tests/`. - [x] Confirm `"sideEffects": false` in `package.json`. - [x] Run `bun scripts/publish.ts --package @suaveplan/cache`. - [x] Update `CLAUDE.md` package listing to include `@suaveplan/cache`. - [x] Archive: move `openspec/changes/enterprise-cache/` to `openspec/archive/2026-04-24-enterprise-cache/` and fold spec delta into `openspec/specs/database/spec.md`.