ts-key-value-cache v1.2.0

Typescript Local Key Value Cache

A key-value cache with string as key and value of any type which support

• time-to-live management
• size control which remove exceed key-value pair in a FIFO manner
• housekeep function to clear the expired item in cache with O(k) times, where k is the number of expired items (Not applied to MAP implementation. For details, see config.)
• in-memory or external storage (e.g. localStorage, Redis) for storing the key-value pair.

Installation

npm i ts-key-value-cache

Examples

TypeScript

import { CacheFactory, CacheOption, QueueConfig, CacheType, TimeoutMode, IKeyValueCache, CachedValue, IMapStorage } from "ts-key-value-cache";

let options: CacheOption = new CacheOption(CacheType.MAP);
options.defaultTTL = 60 * 30; // 30 min
options.maxSize = 100; // this cache keep 100 key-value pair at most

let cache: IKeyValueCache<string> = CacheFactory.make<string>(options);
// One cache can only accept one type of value
// For IKeyValueCache<V>, V is the type of the value it accept
// E.g. the value must be string for this cache

cache.put("abc", "first", 60); // with 60s ttl
cache.put("abc", "testing", null); // replace the last one & using default ttl (30 min)
cache.put("Z", "123"); // will never expired unless it get push out due to cache size limit

cache.get("not exists"); // return undefined
cache.get("abc"); // return "testing"

// use external storage
class SomeMapStorageImplementation implements IMapStorage<string> {...}
cacheInstance = CacheFactory.make<string>(options, new SomeMapStorageImplementation());

Operations on IKeyValueCache

Refer to the index.d.ts, comments in code, or the generated documentation for details.

get(key: string): V | undefined Return value if found in cache and it is not yet expired. Otherwise, return undefined.

put(key: string, value: V, ttl?: number): void Put the item into cache. If there is already a cache with the same key, this will replace the old one and the expired timestamp will be renew ny the new ttl.

delete(key: string): boolean Delete the item from cache with the given key if exists.

clear(): void Clear the cache (& the index for some implementation).

size(): Integer Return the total number of item in this cache.

clearExpiredItems(): void Delete all expired items in the cache.

May take O(N) time (where N is cache current size) for some implementation without index. See CacheType for details.

Config

The cache created is config by the CacheOption passed to the factory. Set up the CacheOption by the setter of its attributes (listed below).

CacheType

MAP

• Simple JS Map that provide the basic cache without index for expiredTS (timestamp).
• Support arbitrary ttl.
• Complicity
  • get, put, delete, clear, size: O(1)
  • clearExpiredItems: O(N)

HEAP

• An extension of MAP which use a min-heap for faster expired item management.
• Support arbitrary ttl.
• Complicity
  • get, put, delete, clear, size: O(1)
  • put: O(log N) for index insertion
  • clearExpiredItems: O(k log N), where k is the number of expired items

If only a few cache item will time out, consider to use MAP instead.

QUEUES

• An extension of MAP which use multiple FIFO queues for expired item management. Each with a fixed ttl.
• Can have a queue with items that won't expired.
• Complicity
  • get, put, delete, clear, size: O(1)
  • clearExpiredItems: O(k), where k is the number of expired items

If there are many possible ttl values, consider to use MAP instead.

If there is only one queue, consider to use MAP or HEAP instead.

TimeoutMode

QueueConfig

Documentation

Download the module from git and run npm run doc to get a full version of doc.