@node-ts-cache/node-cache-storage

In-memory storage adapter for @node-ts-cache/core using node-cache.

Features

• Synchronous operations (no Promises needed)
• Built-in TTL and automatic cleanup
• Multi-get/set operations for batch caching
• Statistics tracking
• Key count limits
• Clone on get/set (data isolation)

Installation

npm install @node-ts-cache/core @node-ts-cache/node-cache-storage

Usage

Basic Usage

import { SyncCache, ExpirationStrategy } from '@node-ts-cache/core';
import NodeCacheStorage from '@node-ts-cache/node-cache-storage';

const storage = new NodeCacheStorage();
const strategy = new ExpirationStrategy(storage);

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

With Options

const storage = new NodeCacheStorage({
	stdTTL: 100, // Default TTL in seconds
	checkperiod: 120, // Cleanup check interval in seconds
	maxKeys: 1000, // Maximum number of keys (-1 = unlimited)
	useClones: true // Clone objects on get/set (data isolation)
});

Async Usage

Works with @Cache decorator as well (operations are still synchronous internally):

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

const storage = new NodeCacheStorage();
const strategy = new ExpirationStrategy(storage);

class UserService {
	@Cache(strategy, { ttl: 300 })
	async getUser(id: string): Promise<User> {
		return await db.users.findById(id);
	}
}

Multi-Operations with @MultiCache

import { MultiCache, ExpirationStrategy } from '@node-ts-cache/core';
import NodeCacheStorage from '@node-ts-cache/node-cache-storage';

const storage = new NodeCacheStorage();
const strategy = new ExpirationStrategy(storage);

class ProductService {
	@MultiCache([strategy], 0, id => `product:${id}`)
	async getProductsByIds(ids: string[]): Promise<Product[]> {
		return await db.products.findByIds(ids);
	}
}

Direct API Usage

const storage = new NodeCacheStorage();
const strategy = new ExpirationStrategy(storage);

// Single operations
strategy.setItem('key', { data: 'value' }, { ttl: 60 });
const value = strategy.getItem<{ data: string }>('key');

// Clear all
strategy.clear();

Constructor Options

Accepts all node-cache options:

| Option | Type | Default | Description | | ---------------- | --------- | ------- | ------------------------------------------ | | stdTTL | number | 0 | Default TTL in seconds (0 = unlimited) | | checkperiod | number | 600 | Automatic delete check interval in seconds | | maxKeys | number | -1 | Maximum number of keys (-1 = unlimited) | | useClones | boolean | true | Clone objects on get/set | | deleteOnExpire | boolean | true | Delete expired keys automatically |

Interface

interface ISynchronousCacheType {
	getItem<T>(key: string): T | undefined;
	setItem(key: string, content: any, options?: any): void;
	clear(): void;
}

interface IMultiSynchronousCacheType {
	getItems<T>(keys: string[]): { [key: string]: T | undefined };
	setItems(values: { key: string; content: any }[], options?: any): void;
	clear(): void;
}

TTL Behavior

When using with ExpirationStrategy:

• node-cache's stdTTL sets the storage-level TTL
• ExpirationStrategy's ttl option sets the strategy-level TTL
• Both apply - the shorter one determines actual expiration

For best results, either:

• Set stdTTL: 0 and let ExpirationStrategy handle TTL
• Or set isCachedForever: true in strategy options and let node-cache handle TTL

Dependencies

• node-cache ^5.1.2

Requirements

• Node.js >= 18.0.0

License

MIT