keyv-s3fifo

S3-FIFO storage adapter for Keyv, powered by the high-performance s3fifo engine.

keyv-s3fifo brings the state-of-the-art S3-FIFO (Simple Scalable Static FIFO) cache eviction algorithm to the Keyv key-value storage ecosystem. S3-FIFO provides significantly higher cache hit ratios compared to traditional LRU and Quick-LRU implementations under scan-heavy and real-world web workloads.

Features

• 🚀 High Performance: Built on top of s3fifo with zero-allocation ring buffers.
• 🎯 Seamless Keyv Integration: Compatible with Keyv v6+, KeyvMemoryAdapter, and multi-tier caching engines like cacheable.
• ⏱️ TTL Support: Full TTL expiration and automatic cleanup.
• 📦 Namespacing: Full support for Keyv namespaces and isolation.
• 📘 TypeScript Ready: Written natively in TypeScript with complete type definitions.

Installation

npm install keyv-s3fifo keyv s3fifo

Quick Start

import Keyv from 'keyv';
import { KeyvS3Fifo } from 'keyv-s3fifo';

// Create a Keyv instance backed by S3-FIFO with maximum capacity of 10,000 items
const store = new KeyvS3Fifo({ max: 10000 });
const keyv = new Keyv({ store });

// Standard Keyv operations
await keyv.set('user:101', { name: 'Alice' });
const user = await keyv.get('user:101'); // { name: 'Alice' }

// Set with TTL (5000 ms)
await keyv.set('session:abc', 'token_data', 5000);

// Delete & Clear
await keyv.delete('user:101');
await keyv.clear();

Using with cacheable (Layer 1 / Layer 2 Caching)

KeyvS3Fifo can serve as an ultra-fast L1 in-memory store alongside an L2 distributed store like Redis:

import { Cacheable } from 'cacheable';
import { KeyvS3Fifo } from 'keyv-s3fifo';
import KeyvRedis from '@keyv/redis';

const primary = new KeyvS3Fifo({ max: 50000 });
const secondary = new KeyvRedis('redis://user:pass@localhost:6379');

const cache = new Cacheable({ primary, secondary });

API

new KeyvS3Fifo(options)

Options

Accepts all configuration options from s3fifo:

• max (number, required): Maximum count of active cache items before eviction occurs (min: 10).
• dispose (function, optional): Callback (key, value, reason) => void triggered when items are evicted or deleted.
• ttlResolution (number, optional): Resolution interval in ms for internal clock updates (default: 100ms).

As well as standard KeyvMemoryAdapterOptions:

• namespace (string, optional): Default prefix namespace for keys.
• keySeparator (string, optional): Key separator string (default: ":").

.s3fifo

Access the underlying S3Fifo cache instance directly:

const store = new KeyvS3Fifo({ max: 1000 });
console.log(store.s3fifo.size); // Returns current resident item count

License

ISC © BJS-kr