Cache



A simple and extensible caching library built on top of a plain database (such as key-value store). It comes with a built-in eviction strategy and can be extended easily to fit various use-cases. It supports both Least Recently Used (LRU) and Least Frequently Used (LFU) eviction strategies out-of-the-box.

Features

- Support for LRU and LFU eviction strategies
- Size-based eviction
- Event-driven architecture
- Pruning of cache
- Customizable cache options

Installation

Install the package with:

``bash
npm install @plaindb/cache
`

Usage

First, import the Cache library.

`js
import Cache from '@plaindb/cache'
`
or
`js
const Cache = require('@plaindb/cache')
`

Basic Usage

`js
const Cache = require('@plaindb/cache')

// Initialize cache with storage and options
const myCache = new Cache(storageInstance, {
strategy: 'LRU',
maxSizeBytes: 1024,
maxSizeItems: 50
})

// Put data into cache
myCache.put('key', 'value')

// Get data from cache
const data = await myCache.get('key')

// Delete data from cache
myCache.del('key')

// Manually prune the cache
myCache.prune()
`

Examples

$3

`js
const myCache = new Cache(storageInstance, {
strategy: 'LFU'
})
`

$3

`js
class MyCustomStrategy extends AbstractEvictionStrategy {
async get(key) {
// Custom logic
}
// ... implement other methods
}

EvictionStrategyFactory.strategyMap['MyCustomStrategy'] = MyCustomStrategy
`

Events

Cache instances are event-driven. Currently, the prune event is supported, which is emitted when the cache is pruned.

`js
myCache.on('prune', (keys) => {
console.log(These keys were pruned: ${keys})
})
`

Documentation

- API Reference

$3

#### constructor(storage, [options])

- storage: The storage instance where the cache will be stored.
- options: An optional object for cache settings, which includes:
- strategy: Eviction strategy. Default is 'LRU'.
- maxSizeBytes: Maximum cache size in bytes.
- maxSizeItems: Maximum number of items in cache.

#### Methods

- get(key): Fetches the item from cache by key.
- put(key, value): Inserts or updates an item into the cache.
- del(key): Removes an item from the cache by key.
- prune(): Manually prunes the cache based on the eviction strategy.

$3

You can create your own eviction strategy by extending AbstractEvictionStrategy. Implement the following methods:

- put(key, value)
- get(key)
- del(key)
- prune()

After creating, register your strategy like this:

`js
EvictionStrategyFactory.strategyMap['MyStrategy'] = MyStrategy
`

Tests

In order to run the test suite, simply clone the repository and install its dependencies:

`bash
git clone https://gitlab.com/frenware/framework/plaindb/cache.git
cd cache
npm install
`

To run the tests:

`bash
npm test
`

Contributing

Thank you! Please see our contributing guidelines for details.

Donations

If you find this project useful and want to help support further development, please send us some coin. We greatly appreciate any and all contributions. Thank you!

Bitcoin (BTC):
`
1JUb1yNFH6wjGekRUW6Dfgyg4J4h6wKKdF
`

Monero (XMR):
`
46uV2fMZT3EWkBrGUgszJCcbqFqEvqrB4bZBJwsbx7yA8e2WBakXzJSUK8aqT4GoqERzbg4oKT2SiPeCgjzVH6VpSQ5y7KQ
``

License

@plaindb/cache is MIT licensed.