neophi / sieve-cache

A performant implementation of the SIEVE caching algorithm that implements Map properties and methods.

sieve-cache

A performant implementation of the SIEVE caching algorithm that implements Map properties and methods designed for Node.js 20+.

Installation

npm install @neophi/sieve-cache --save

Usage

import { SieveCache } from "@neophi/sieve-cache";

const sieveCache = new SieveCache<string, string>(2);
sieveCache.set("key", "value");
// "value"
sieveCache.get("key");
sieveCache.set("key2", "value2");
// triggers eviction via SIEVE algorithm
sieveCache.set("key3", "value3");
// false
sieveCache.has("key2");

The API exposes the JS Map properties and methods.

Options

constructor(maxSize: number, options: Partial<SieveCacheOptions<K, V>> = {})

The maxSize of the cache must be at least 1 and less than 4,294,967,295.

The existingSetBehavior option changes the behavior of the SIEVE visited state when updating a key that already exists in the Map. The default is ExistingSetBehavior.VISITED_SKIP which means the existing visited state is not modified.

The evictHook option is a function (key: K, value: V) => void that can be configured to be called with the details of the evicted item after the cache has been updated.

import { SieveCache, ExistingSetBehavior } from "@neophi/sieve-cache";

const sieveCache = new SieveCache<string, string>(2, {
  existingSetBehavior: ExistingSetBehavior.VISITED_TRUE,
  evictHook: (key, value) => { console.log(`Evicted ${key} => ${value}`); }
});

Performance

Always benchmark your specific use case since many runtime, key type, and object type differences can impact the performance of an implementation. With that said this implementation compares favorably to established libraries such as lru-cache and mnemonist. For an extensive benchmark see cache-playground.

Credits

This implementation was inspired by Implementing an efficient LRU cache in JavaScript.

Contributing

Everyone interacting with this project is expected to follow the code of conduct.

License

Released under the MIT License.

sieve-cache's Issues

Great work!

Great work! Do you mind adding the sieve-cache hashtag? Sieve hashtag is also used for other purposes. Having a unique hashtag will help users find this library much easier. Thank you!