117 lines
5.2 KiB
Markdown
117 lines
5.2 KiB
Markdown
# Tasks: enterprise-browser-cache-browser
|
|
|
|
**Change ID**: enterprise-browser-cache-browser
|
|
**Package**: `@suaveplan/cache-browser`
|
|
**Target path**: `browser/storage/cache-browser`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/cache`, `@suaveplan/events`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/broadcast-channel`
|
|
|
|
---
|
|
|
|
## 0. Pre-flight (non-negotiable)
|
|
|
|
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
|
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
|
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
|
|
|
## 1. Scaffold
|
|
|
|
- [ ] Create directory tree per `proposal.md`.
|
|
- [ ] `package.json` v0.0.0:
|
|
- `"sideEffects": ["./dist/register.js"]` — only the register entry has side effects
|
|
- Subpath exports: `"."`, `"./localstorage"`, `"./sessionstorage"`, `"./indexeddb"`, `"./register"`, `"./types"`
|
|
- `dependencies`: `@suaveplan/cache workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/broadcast-channel workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
|
|
- `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `fake-indexeddb catalog:testing`, `@playwright/test catalog:testing`, `@suaveplan/testing workspace:^`
|
|
- [ ] `tsconfig.json`, `vitest.config.ts` (pool: forks, `fileParallelism: false` for browser tests).
|
|
|
|
---
|
|
|
|
## 2. Error codes
|
|
|
|
- [ ] `CACHE_QUOTA_EXCEEDED`, `CACHE_SERIALIZATION_FAILED`, `INDEXEDDB_NOT_AVAILABLE`.
|
|
- [ ] `registerCacheBrowserErrorCodes()` — call eagerly.
|
|
|
|
---
|
|
|
|
## 3. Serializer + eviction interfaces (`src/utils/`)
|
|
|
|
- [ ] `serialization/`: `Serializer<T>` interface, `defaultSerializer`, `defaultDeserializer`, `isSerializable`, `safeDeserialize`. Tests + md.
|
|
- [ ] `quota/`: quota utils. Tests + md.
|
|
- [ ] `storage-events/`: `StorageEventHandler`. Tests + md.
|
|
- [ ] `src/eviction/lru-eviction/`, `lfu-eviction/`, `ttl-first-eviction/`: each implements `EvictionStrategy`. Tests + md.
|
|
|
|
---
|
|
|
|
## 4. IndexedDB cache (`src/indexeddb/`)
|
|
|
|
Split into four sub-modules ≤300 lines each:
|
|
|
|
- [ ] `store/store.ts`: CRUD via IDB transactions, `get`/`set`/`delete`/`clear`/`list`.
|
|
- [ ] `ttl/ttl.ts`: `expiresAt` index, proactive sweep via `requestIdleCallback`.
|
|
- [ ] `quota/quota.ts`: quota check before write; `CACHE_QUOTA_EXCEEDED` on fail.
|
|
- [ ] `events/events.ts`: broadcast-channel invalidation hooks.
|
|
- [ ] `indexeddb/indexeddb.ts`: orchestrator composing above.
|
|
- [ ] `getMetrics()`: returns `CacheMetrics` (size, hitCount, missCount, evictionCount) — no private-property access in tests.
|
|
- [ ] Tests: CRUD, TTL expiry, quota guard, cross-tab invalidation (via broadcast-channel), batch ops. All test files ≤500 lines.
|
|
- [ ] Write `.md` per module.
|
|
|
|
---
|
|
|
|
## 5. LocalStorage cache (`src/localstorage/`)
|
|
|
|
Split similarly: `store/`, `ttl/`, `quota/`, `events/`, `localstorage/`.
|
|
|
|
- [ ] Cross-tab invalidation via `StorageEventHandler` + optional `broadcastChannel`.
|
|
- [ ] `getMetrics()` introspection.
|
|
- [ ] Tests ≤500 lines. Write `.md` per module.
|
|
|
|
---
|
|
|
|
## 6. SessionStorage cache (`src/sessionstorage/`)
|
|
|
|
Split: `store/`, `ttl/`, `sessionstorage/`.
|
|
|
|
- [ ] `getMetrics()` introspection.
|
|
- [ ] Tests ≤500 lines. Write `.md` per module.
|
|
|
|
---
|
|
|
|
## 7. Register entry (`src/register.ts`)
|
|
|
|
- [ ] Call `CacheFactory.register('localStorage', () => new LocalStorageCache(...))` etc.
|
|
- [ ] This file is the only side-effect entry; matches `sideEffects` array.
|
|
|
|
---
|
|
|
|
## 8. OTel metrics
|
|
|
|
- [ ] Wire counters + histograms in each cache implementation's CRUD methods.
|
|
|
|
---
|
|
|
|
## 9. Playwright E2E (`e2e/cache-browser.spec.ts`)
|
|
|
|
- [ ] Three browser contexts (Chromium, WebKit, Firefox via Playwright).
|
|
- [ ] Assert: IndexedDB CRUD, LocalStorage TTL, cross-tab invalidation (two tabs, one writes, other reads updated value), quota-exceeded eviction.
|
|
|
|
---
|
|
|
|
## 10. Integration test (`tests/integration.test.ts`)
|
|
|
|
- [ ] All three caches via the same `Cache` interface.
|
|
- [ ] Eviction strategies (LRU, LFU, TTL-first) under simulated quota pressure.
|
|
- [ ] Serializer swap: replace JSON with a custom `Serializer<User>`.
|
|
|
|
---
|
|
|
|
## 11. Docs + verify
|
|
|
|
- [ ] Write `.md` per module (≥200 words, API reference, examples).
|
|
- [ ] Write `README.md` with subpath table, serializer guide, eviction strategy table, cross-tab section.
|
|
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/cache-browser` — green.
|
|
- [ ] `bunx turbo test:coverage` — 100%.
|
|
- [ ] No `@ts-expect-error` in `src/` or tests.
|
|
- [ ] `sideEffects` declaration correctly reflects only `register.ts`.
|
|
- [ ] Playwright E2E green on Chromium, WebKit, Firefox.
|
|
- [ ] `bun scripts/publish.ts --package @suaveplan/cache-browser`.
|
|
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-browser-cache-browser/`.
|