node-ts-cache

Simple and extensible caching module for TypeScript/Node.js with decorator support.

Features

• Decorator-based caching - Use @Cache, @SyncCache, and @MultiCache decorators for elegant caching
• Multiple storage backends - Memory, File System, Redis, LRU Cache, and more
• Flexible expiration strategies - TTL-based expiration with lazy or eager invalidation
• Multi-tier caching - Chain multiple cache layers (e.g., local LRU + remote Redis)
• TypeScript-first - Full type safety with comprehensive interfaces
• ESM support - Modern ES modules with Node.js 18+

Quick Start

npm install @node-ts-cache/core

import{Cache,ExpirationStrategy,MemoryStorage}from'@node-ts-cache/core';constcacheStrategy=newExpirationStrategy(newMemoryStorage());classUserService{
@Cache(cacheStrategy,{ttl: 300})asyncgetUser(id: string): Promise<User>{// This result will be cached for 5 minutesreturnawaitfetchUserFromDatabase(id);}}

Packages

This is a monorepo containing the following packages:

Core Package

Package	Version	Description
@node-ts-cache/core		Core caching module with decorators, strategies, and built-in storages

Storage Adapters

Package	Version	Description
@node-ts-cache/redis-storage		Redis storage using redis package (v4.x)
@node-ts-cache/ioredis-storage		Redis storage using ioredis with compression support
@node-ts-cache/node-cache-storage		In-memory cache using node-cache
@node-ts-cache/lru-storage		LRU cache with automatic eviction
@node-ts-cache/lru-redis-storage		Two-tier caching (local LRU + remote Redis)
@node-ts-cache/elasticsearch-storage		Elasticsearch storage for search-optimized caching
@node-ts-cache/memcached-storage		Memcached storage for distributed caching
@node-ts-cache/valkey-storage		Valkey storage (Redis-compatible, open source)

Documentation

For detailed documentation, see the main package README.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│ Application │
├─────────────────────────────────────────────────────────────────┤
│ Decorators Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ @Cache │ │ @SyncCache │ │ @MultiCache │ │
│ │ (async) │ │ (sync) │ │ (multi-tier/batch) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
├──────────┼────────────────┼────────────────────┼────────────────┤
│ └────────────────┼────────────────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Strategy │ │
│ │ (Expiration) │ │
│ └───────┬────────┘ │
├──────────────────────────┼──────────────────────────────────────┤
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────────────────┐ │
│ │ Storage Layer │ │
│ ├────────┬──────┬───────┬─────┬───────────┬───────────────┬────────────┬──────────┤ │
│ │ Memory │ FS │ Redis │ LRU │ LRU+Redis │ Elasticsearch │ Memcached │ Valkey │ │
│ └────────┴──────┴───────┴─────┴───────────┴───────────────┴────────────┴──────────┘ │
└─────────────────────────────────────────────────────────────────┘

Choosing a Storage

Storage	Type	Use Case	Features
MemoryStorage	Sync	Development, small datasets	Zero config, bundled
FsJsonStorage	Async	Persistent local cache	File-based, survives restarts
NodeCacheStorage	Sync	Production single-instance	TTL support, multi-ops
LRUStorage	Sync	Memory-constrained apps	Auto-eviction, size limits
RedisStorage	Async	Distributed systems	Shared cache, redis v4
RedisIOStorage	Async	Distributed systems	Compression, modern ioredis
LRUWithRedisStorage	Async	High-performance distributed	Local + remote tiers
ElasticsearchStorage	Async	Search-integrated caching	Full-text search, scalable
MemcachedStorage	Async	High-performance distributed	Simple, fast, widely supported
ValkeyStorage	Async	Distributed systems	Redis-compatible, open source

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (for decorator support)

Development

# Install dependencies
npm install
# Build all packages
npm run build
# Run tests
npm test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Credits

Originally created by hokify, now maintained by simllll.