Cacheable

Cacheable is a distributed caching library for Node.js built on top of the Keyv storage engine, providing simple layered (memory + remote) caching with an enterprise-grade feature set. It combines an in-memory LRU cache (CacheableMemory) as a fast primary layer with any Keyv-compatible secondary store (Redis, etc.), non-blocking writes, and a CacheSync pub/sub mechanism for keeping multiple instances consistent.

Part of the broader jaredwray/cacheable monorepo (which also ships cache-manager, cacheable-request, flat-cache, and other caching utilities), Cacheable is under active, regular maintenance with comprehensive test coverage and both ESM and CommonJS builds.

What You Get

• Cacheable class combining a fast in-memory primary store with an optional remote secondary store
• CacheableMemory - a standalone LRU cache with TTL/expiration support
• Function memoization via wrap() and getOrSet() with stampede protection for sync and async functions
• Hooks and events (before/after set, get, delete) to extend caching behavior
• CacheSync for distributed cache invalidation across instances via pub/sub
• Non-blocking secondary-store writes so remote latency doesn’t block reads/writes

Common Use Cases

• Adding a fast in-memory layer in front of Redis to cut round-trips for hot keys
• Memoizing expensive async function calls (e.g. DB queries) with automatic TTL
• Keeping cache state consistent across multiple app instances via CacheSync
• Tag-based invalidation of related cache entries after a data update
• Building a resilient caching layer that degrades gracefully if the remote store is offline

Under The Hood

Architecture - The packages/cacheable module (within the jaredwray/cacheable pnpm monorepo) centers on a Cacheable class in src/index.ts that composes a primary Keyv instance (defaulting to CacheableMemory, an in-memory LRU store defined in src/memory.ts equivalents) with an optional secondary Keyv-compatible store; reads check primary then fall back to secondary, writes propagate to both non-blockingly, and sync.ts implements CacheSync, a pub/sub layer that broadcasts invalidations to keep multiple processes’ primary caches consistent.

Tech Stack - Written in TypeScript (97%+ of the monorepo), built with tsdown to emit both ESM (.mjs) and CommonJS (.cjs) outputs with generated .d.ts types, and depends on the keyv storage-adapter ecosystem (@keyv/redis, lru-cache) rather than hardcoding a specific backend, using pnpm workspaces to share tooling (biome for linting) across the monorepo’s ten-plus packages.

Code Quality - The monorepo enforces test coverage via Codecov badges and a GitHub Actions tests.yml workflow; the cacheable package itself is a relatively small, focused module (~2,200 lines across src/), and the monorepo’s shared CONTRIBUTING.md/AGENTS.md/CLAUDE.md files indicate deliberate conventions for contributors and AI coding agents alike.

API Design - The API is intentionally minimal - new Cacheable({secondary}) plus .get()/.set()/.delete() covers the common case, with TTL shorthand strings ('1h', '1d') reducing boilerplate, and wrap()/getOrSet() let existing functions be memoized without restructuring calling code; hooks and typed events provide an escape hatch for advanced use without complicating the base API.