@node-ts-cache/core

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

Installation

npm install @node-ts-cache/core

Quick Start

import { Cache, ExpirationStrategy, MemoryStorage } from '@node-ts-cache/core';

const cacheStrategy = new ExpirationStrategy(new MemoryStorage());

class UserService {
	@Cache(cacheStrategy, { ttl: 60 })
	async getUser(id: string): Promise<User> {
		return await database.findUser(id);
	}
}

Storage Engines

The core package includes MemoryStorage and FsJsonStorage. Additional storage backends are available as separate packages:

| Package | Storage Type | Sync/Async | Use Case | | -------------------------------------- | --------------------------------------------------------------------- | ---------- | -------------------------------------- | | @node-ts-cache/core | MemoryStorage | Sync | Development, simple caching | | @node-ts-cache/core | FsJsonStorage | Async | Persistent local cache | | @node-ts-cache/node-cache-storage | node-cache | Sync | Production single-instance with TTL | | @node-ts-cache/lru-storage | lru-cache | Sync | Memory-bounded with automatic eviction | | @node-ts-cache/redis-storage | redis (v4.x) | Async | Shared cache | | @node-ts-cache/ioredis-storage | ioredis | Async | Shared cache with compression | | @node-ts-cache/lru-redis-storage | LRU + Redis | Async | Two-tier: fast local + shared remote | | @node-ts-cache/elasticsearch-storage | elasticsearch | Async | Search-integrated caching | | @node-ts-cache/memcached-storage | memcached | Async | High-performance distributed cache | | @node-ts-cache/valkey-storage | iovalkey | Async | Redis-compatible, open source |

Decorators

@Cache

Caches async method results. Cache key is generated from class name, method name, and arguments.

class ProductService {
	@Cache(strategy, { ttl: 300 })
	async getProduct(id: string): Promise<Product> {
		return await db.products.findById(id);
	}
}

Note: @Cache always returns a Promise since cache operations may be asynchronous.

@SyncCache

Caches synchronous method results without converting to Promises. Use with synchronous storages like MemoryStorage or LRUStorage.

class ConfigService {
	@SyncCache(strategy, { ttl: 60 })
	getConfig(key: string): ConfigValue {
		return computeConfig(key);
	}
}

@MultiCache

Multi-tier caching with batch operations for array-based lookups.

class UserService {
	@MultiCache([localCache, redisCache], 0, id => `user:${id}`, { ttl: 300 })
	async getUsersByIds(userIds: string[]): Promise<User[]> {
		return await db.users.findByIds(userIds);
	}
}

Direct API Usage

Use the caching strategy directly without decorators:

const cache = new ExpirationStrategy(new MemoryStorage());

// Get item
const value = await cache.getItem<Data>('key');

// Set item with TTL
await cache.setItem('key', data, { ttl: 300 });

// Delete item
await cache.setItem('key', undefined);

// Clear all
await cache.clear();

ExpirationStrategy Options

| Option | Type | Default | Description | | ----------------- | --------- | ------- | --------------------------------------------------------------------------------- | | ttl | number | 60 | Time to live in seconds | | isLazy | boolean | true | If true, delete on access after expiration. If false, delete via setTimeout | | isCachedForever | boolean | false | If true, items never expire |

// Cache for 5 minutes with lazy expiration
await strategy.setItem('key', value, { ttl: 300, isLazy: true });

// Cache forever
await strategy.setItem('key', value, { isCachedForever: true });

// Cache with eager expiration (auto-delete after TTL)
await strategy.setItem('key', value, { ttl: 10, isLazy: false });

Custom Key Strategies

Override default key generation by implementing ISyncKeyStrategy or IAsyncKeyStrategy:

class CustomKeyStrategy implements ISyncKeyStrategy {
	getKey(className: string, methodName: string, args: any[]): string | undefined {
		if (args[0] === 'skip') return undefined; // Skip caching
		return `${className}::${methodName}::${args.join('-')}`;
	}
}

class MyService {
	@Cache(strategy, { ttl: 60 }, new CustomKeyStrategy())
	async getData(id: string): Promise<Data> {
		return fetchData(id);
	}
}

Advanced Features

Call Deduplication

Concurrent calls with the same cache key share the same pending promise:

// All three calls share one database request
const [a, b, c] = await Promise.all([
	service.fetchData('123'),
	service.fetchData('123'),
	service.fetchData('123')
]);

Null vs Undefined

• undefined: Cache miss or skip caching
• null: Cached value (e.g., "not found" result)

async findUser(id: string): Promise<User | null> {
  const user = await db.findUser(id);
  return user ?? null; // Cache "not found" as null
}

Environment Variables

| Variable | Description | | ------------------------- | --------------------------------------------------- | | DISABLE_CACHE_DECORATOR | Set to any value to disable all @Cache decorators |

More Documentation

See ADVANCED.md for:

• Interface definitions for implementing custom storages
• Detailed storage configuration examples
• @MultiCache in-depth usage
• Error handling patterns

License

MIT License