feat: add @nest-native/cache read caching (ninth library)#61
Merged
Conversation
Dogfood @stalefree/core + @nest-native/cache: expensive reads cached in an in-memory L1 with tag-based invalidation, TTL as the delivery backstop. - cache.setup.ts: CacheModule.forRootAsync; the socket bus is wired when CACHE_SOCKET_PATH is set (the app + start:worker split — the same-machine tier built for exactly this shape); in-process coherence otherwise - projects.router: list/get wrapped with org-scoped keys + tags; create invalidates the org's project tag (typed useFactory + explicit @Inject — both lessons the earlier dogfoods taught are already honored upstream) - activity.router: the feed cached per project; ActivityService.record invalidates at the projection write site — the event-driven feed evicts its own cache when the handler writes (sync better-sqlite3 tx: no mid-tx interleaving, so pre-commit invalidation is unobservable here; documented) - env: CACHE_TTL_MS (default 30s) + CACHE_SOCKET_PATH (optional) - e2e: a TEN-MINUTE TTL makes staleness glaring; both specs prove freshness within seconds of the mutation — tag invalidation, not expiry - README + constitution reframed eight -> nine libraries/chapters Gates: typecheck, lint, complexity, client-smoke, 86 pass / 0 fail (live- Kafka spec self-skips without Docker).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Dogfoods the brand-new
@stalefree/core+@nest-native/cache(published tonight, 0.1.0), bringing the reference app to 9/9 nest-native libraries: expensive reads cached in an in-memory L1 with tag-based invalidation — mutations evict by tag, and every entry's TTL is only the delivery backstop.The pattern (the chapter readers copy)
projects.list/getandactivity.listwrap their synchronous services with org-scoped keys (org:7:project:42) and tags — services stay cache-free and sync.projects.createevicts the org's project tag;ActivityService.recordinvalidates the project's feed tag at the projection write site — the event-driven feed evicts its own cache when the outbox handler writes the row. (Sync better-sqlite3 transactions mean no mid-tx interleaving, so pre-commit invalidation is unobservable here; the caveat for async drivers is documented inline.)CACHE_SOCKET_PATHwires@stalefree/core/socket's unix-socket mesh for the app +start:workersplit — the same-machine tier built for exactly this topology.Proof
test/e2e/stalefree-cache.spec.tsruns with a ten-minute TTL, so stale data would be glaring for the whole run:projects.listcached →projects.create→ the next read reflects the new project immediately (tag invalidation, provably not expiry)activity.listcached →tasks.create→ claimer tick → the feed shows the event row immediately — the projection's write-site invalidation working end to endFeedback-loop note
No library friction to ship upstream this time — the two lessons earlier dogfoods taught (
useFactory: (...args: any[]), full provider exports) were baked into@nest-native/cachefrom day one, and both held. A pre-publish two-agent adversarial review of the core had already caught and fixed 2 criticals + 4 real defects, which is likely why this integration went through clean.Gates
typecheck, lint, complexity (≤15), client-smoke, 86 pass / 0 fail (live-Kafka spec self-skips — Docker not run for this PR). README + constitution reframed eight → nine.