KeyvNest


KeyvNest is a hierarchical caching adapter for the Keyv module. It allows you to nest multiple caching layers, such as memory cache, disk cache, and network cache, to create a multi-layered caching mechanism that boosts user experience by optimizing data retrieval across different storage tiers.

Features

- 🚀 Multi-layer caching: Nest unlimited cache layers with automatic promotion
- ⚡ Performance optimized: Fast reads from primary cache with automatic fallback
- 🔄 Write concern control: Fine-grained control over synchronous/asynchronous writes
- 🔌 Keyv compatible: Works seamlessly with any Keyv store adapter
- 📦 TypeScript support: Full type definitions included
- 🎯 Simple API: Easy to use and integrate

Table of Contents

- Features
- Installation
- Usage
- API
- Examples
- Contributing
- License

Installation

You can install the module via npm:

``sh
npm install keyv-nest
`

Or using bun:

`sh
bun add keyv-nest
`

Usage

First, import the module and create instances of your cache stores. Then, use KeyvNest to create a hierarchical caching structure.

`typescript
import Keyv from 'keyv';
import KeyvNest from 'keyv-nest';

const memoryCache = new Keyv({ store: new Map() });
const diskCache = new Keyv({ store: new KeyvFileStore('/path/to/store') });
const networkCache = new Keyv({ store: new SomeNetworkStore() });

const nestedCache = KeyvNest(memoryCache, diskCache, networkCache);

(async () => {
await nestedCache.set('foo', 'bar');
const value = await nestedCache.get('foo');
console.log(value); // 'bar'
})();
`

$3

KeyvNest supports write concern control to manage how data is persisted across cache layers:

`typescript
import Keyv from 'keyv';
import KeyvNest from 'keyv-nest';

const memoryCache = new Keyv({ store: new Map() });
const diskCache = new Keyv({ store: new KeyvFileStore('/path/to/store') });

const nestedCache = KeyvNest(memoryCache, diskCache);

// Write concern = 0: Write to first layer only, propagate asynchronously
await nestedCache.set('key1', 'value1', { writeConcern: 0 });

// Write concern = 1: Write to first two layers, propagate rest asynchronously
await nestedCache.set('key2', 'value2', { writeConcern: 1 });

// Default: Write to all layers synchronously
await nestedCache.set('key3', 'value3');
`

$3

`typescript
export const store = (g.store ??= KeyvNest(
{
get: (key) => console.log("kv.get " + key),
set: (key, v) => console.log("kv.set " + key),
delete: () => console.log("kv.delete"),
clear: () => console.log("kv.clear"),
},
new QuickLRU({ maxSize: 1000 }),
new KeyvDirStore("./.cache/" + collection),
new KeyvMongo(MONGODB_URI, { collection })
));

export const kv = new Keyv({ store, ttl: enhancedMs("4w") });
export const kv1m = new Keyv({ store, ttl: enhancedMs("1m") });
export const kv1d = new Keyv({ store, ttl: enhancedMs("1d") });
export const kv1w = new Keyv({ store, ttl: enhancedMs("1w") });
export const kv1y = new Keyv({ store, ttl: enhancedMs("1y") });

export const cache1m = KeyvCachedWith(kv1m);
export const cache1d = KeyvCachedWith(kv1d);
export const cache1w = KeyvCachedWith(kv1w);
export const cache1y = KeyvCachedWith(kv1y);
`

API

$3

#### KeyvNest(cache: KeyvStore, store: KeyvStore, ...rest: KeyvStore[]): KeyvStore

Creates a nested cache adapter that allows for multi-layered caching.

- cache: The primary cache store (usually memory cache).
- store: The secondary cache store (usually disk cache).
- rest: Additional cache stores (e.g., network cache).

Returns a KeyvStore instance with the following methods:

#### get(key: string): Promise

Retrieves a value from the cache hierarchy. If the value is found in the primary cache, it is returned. Otherwise, it checks the secondary cache and so on. If a value is found in any cache layer, it is promoted to the primary cache.

- key: The cache key.
- returns: A promise that resolves to the cached value or undefined.

#### set(key: string, value: T, options?: number | KeyvNestOptions): Promise

Sets a value in all layers of the cache hierarchy.

- key: The cache key.
- value: The value to cache.
- options: Optional TTL (number) or options object:
- ttl: Time-to-live in milliseconds
- writeConcern: Controls write propagation behavior:
- 0: Write to first layer only, propagate asynchronously to others
- 1: Write to first two layers synchronously, propagate rest asynchronously
- >=2: Write to N+1 layers synchronously
- undefined (default): Write to all layers synchronously
- returns: A promise that resolves when the operation has completed.

#### delete(key: string): Promise

Deletes a value from all layers of the cache hierarchy.

- key: The cache key.
- returns: A promise that resolves when the operation has completed.

#### clear(): Promise

Clears all values from all layers of the cache hierarchy.

- returns: A promise that resolves when the operation has completed.

#### getMany(keys: string[]): Promise>>

Retrieves multiple values from the cache hierarchy. Missing values are fetched from deeper layers and promoted to the primary cache.

- keys: Array of cache keys.
- returns: A promise that resolves to an array of cached values.

Examples

Here is an example of using KeyvNest with memory and disk caches:

`typescript
import Keyv from 'keyv';
import KeyvNest from 'keyv-nest';

const memoryCache = new Keyv({ store: new Map() });
const diskCache = new Keyv({ store: new KeyvFileStore('/path/to/store') });

const nestedCache = KeyvNest(memoryCache, diskCache);

(async () => {
await nestedCache.set('username', 'john_doe');
const username = await nestedCache.get('username');
console.log(username); // 'john_doe'

await nestedCache.delete('username');
const deletedUsername = await nestedCache.get('username');
console.log(deletedUsername); // undefined

await nestedCache.clear();
})();
``

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any feature requests, bug reports, or improvements.

License

This module is open-source and licensed under the MIT License. For more details, see the LICENSE file.