How jaredwray/cacheable works
Project Type and Purpose
• This is an open-source monorepo (“Cacheable Project”) that bundles multiple Node.js caching libraries as independent packages.
• Its goal is to provide a suite of caching solutions (in-memory, file-based, HTTP-cache compliant, Keyv-backed, etc.) and documentation (website) under a single workspace, managed with pnpm.
File-Structure Analysis
• Top level:
• .github/workflows/… – CI definitions (tests, codecov, deploy docs)
• docker-compose.yml – brings up Redis for integration tests
• pnpm-workspace.yaml, package.json – configure the mono-repo
• packages/
• cacheable – core, multi-layer caching framework (layer1, layer2)
• cache-manager – drop-in manager for NestJS and others
• cacheable-request – HTTP wrapper with RFC-compliant caching
• flat-cache, file-entry-cache, @cacheable/node-cache – specialized stores
• website – static docs generator & deployment
• Each package has its own src/, test/, tsconfig.json, and build config (vite.config.ts or similar).
README Insights
• Confirms the repo’s focus on npm-distributed caching packages, their download stats, and interdependence (all built on Keyv).
• Mentions prerequisites (Redis via Docker) and standard build/test flows (pnpm build, pnpm test).
a. Main Components
• Monorepo root & workspace manager (pnpm)
• GitHub Actions CI/CD pipeline
• Dockerized Redis instance (for tests & examples)
• Package modules:
1. cacheable (core framework)
2. cache-manager (NestJS adapter)
3. cacheable-request (HTTP layer)
4. flat-cache (in-memory + file persistence)
5. file-entry-cache (file metadata store)
6. @cacheable/node-cache (replacement node-cache)
• External Dependencies & Services:
• Keyv backends (Redis, memory, files)
• HTTP endpoints (for cacheable-request)
• Filesystem (for flat-cache, file-entry-cache)
• Documentation Website generator & host
b. Relationships & Data Flows
• Developers push code → GitHub Actions → run tests in each package (spinning up Redis via docker-compose) → publish to npm & deploy docs.
• Applications import any package:
• If using cacheable or cache-manager, at runtime calls go through the core module → layered caches → Keyv adapters → storage backends.
• If using cacheable-request, HTTP calls flow into its caching layer → underlying Keyv store → network or cache hit.
• flat-cache and file-entry-cache operate directly on the filesystem for persistence.
• @cacheable/node-cache uses in-process memory store.
c. Architectural Patterns & Principles
• Monorepo with isolated, independently versioned packages
• Workspace sharing of charted dependencies & build scripts
• Adapter pattern (Keyv adapters for Redis, memory, file)
• Layered caching (L1 in-memory, L2 remote or file)
• CI/CD as code (GitHub workflows + docker-compose for test dependencies)
d. Key Technologies & Frameworks
• Node.js & TypeScript
• pnpm workspaces
• Keyv (abstracted pluggable store)
• Vite (build/test config)
• Docker (Redis for integration)
• GitHub Actions (CI/CD)
• Docula (for website)